tw-video-player视频播放器使用说明文档

此播放器插件(下文简称播放器)，仅用于播放独立视频或包含单层目录结构的课程视频列表

更新日志

2023-01-16 v1.0.19-rc

修复了当关闭自动播放时切换当前播放的视频时，播放状态没有正确同步的问题

2023-01-16 v1.0.18-rc

新增了ref转发，暴露出了play和pause两个方法，可用于手工控制播放器播放，利用此特性可以实现3s后播放视频的效果

const videoPlayerRef = useRef(null);

const play = () => {
    videoPlayerRef.current.play();
};

const pause = () => {
    videoPlayerRef.current.pause();
};

<VideoPlayer ref={videoPlayerRef} />

2023-01-12 v1.0.17-rc

修复了在MacOS 13.x版本的系统上，鼠标事件不存在path属性导致报错的问题

2023-01-07 v1.0.16-rc

新增了onVideosDurationUpdate事件回调，当列表中的视频时长正常更新后会触发该事件，返回列表中视频的时长信息，单位为秒。

const videosDurationUpdate = (durations) => {
    console.log(durations);
};

<VideoPlayer onVideosDurationUpdate={videosDurationUpdate} />

2023-01-06 v1.0.15-rc

优化了首次渲染时的性能

2023-01-06 v1.0.14-rc

新增了autoplay属性，类型为boolean，可控制播放器是否自动播放

一、获得插件

npm i tw-video-player

上述命令可在项目中安装播放器插件

二、快速上手

import React from 'react';
import VideoPlayer from 'tw-video-player';

function App() {
    return (
        <div id="app">
            <VideoPlayer src="https://xxx.video.com/xxx/yyy/zzz.mp4" width={1600} height={900} />
        </div>
    )
}

最简单的使用方式便是直接调用 <VideoPlayer src="xxx.mp4" />组件，传入唯一的必传参数src即可

三、属性接口

通用类型描述

interface VideoPlayerSource {
    sources: VideoPlayerSourceItem | VideoPlayerSourceItem[];
}

interface VideoPlayerSourceItem {
    title: string; // 视频标题
    src: string; // 视频链接地址
    videoCover?: string; // 视频封面图片地址，非必须
    duration?: number; // 视频长度，单位：秒，非必须
    startTime?: number; // 视频开始播放的位置，单位：秒，非必须
}

1. src

视频链接URL

属性名：src
类型：string | string[]
是否必须：是，但和contents属性互斥，当两个属性都存在时，src将被忽略
示例：

const videoURL = 'http://xxx.yy.zz/aaa/bbb/ccc.mp4';

<VideoPlayer src={videoURL} />

// or

<VideoPlayer src="http://xxx.yy.zz/aaa/bbb/ccc.mp4" />

2. contents

视频列表目录

属性名：contents
类型：VideoPlayerContentsItem[]
是否必须：是，但和src属性互斥，当两个属性都存在时，src将被忽略
示例：

const courseVideoList = [
    {
        title: '初识HTML', // 视频标题
        src: 'http://twuc.thoughtworks.com/course/front-end/lesson-1.mp4', // 视频链接地址
        videoCover: 'http://twuc.thoughtworks.com/course/front-end/lesson-1.cover.png', // 视频封面图片地址，非必须
        duration: 612, // 视频长度，单位：秒，非必须
        startTime: 0 // 视频开始播放的位置，单位：秒，非必须
    },
    {
        title: 'CSS层叠样式表',
        src: 'http://twuc.thoughtworks.com/course/front-end/lesson-2.mp4',
        videoCover: 'http://twuc.thoughtworks.com/course/front-end/lesson-2.cover.png',
        duration: 1386,
        startTime: 0
    },
    ...
];

<VideoPlayer contents={courseVideoList} />

3. width

宽度

属性名：width
类型：number
是否必须：否，但和height属性必须同时使用
示例：

<VideoPlayer src="xxx.mp4" width={1600} height={900} />

4. height

高度

属性名：height
类型：number
是否必须：否，但和width属性必须同时使用
示例：

<VideoPlayer src="xxx.mp4" width={1600} height={900} />

5. currentIndex

当前正在播放的视频索引，相对于contents目录索引位置

属性名：currentIndex
类型：number
是否必须：否
默认值：0
是否受控：是，改变该属性将立刻变更正在播放的视频
示例：

<VideoPlayer contents={videoList} currentIndex={3} /> // 视频将从列表中第四个开始播放

6. onCurrentIndexChange

当前播放的视频索引发生变化时的回调函数

属性名：onCurrentIndexChange
类型：function(index: number): void;
是否必须：否
默认值：undefined
示例：

const currentIndexChanged = (index) => {
    console.log(index);
    // TODO
}

<VideoPlayer contents={videoList} onCurrentIndexChange={currentIndexChanged} />

7. onPlay

视频开始播放时的回调函数，可以配合播放暂停的回调函数实现类似暂停播放时插播广告的效果

属性名：onPlay
类型：function(index?: number): void;
是否必须：否
默认值：undefined
示例：

const onVideoPlay = (index) => {
    console.log(index);
    // TODO
}

<VideoPlayer contents={videoList} onPlay={onVideoPlay} />

8. onPause

视频暂停播放时的回调函数

属性名：onPause
类型：function(index?: number): void;
是否必须：否
默认值：undefined
示例：

const onVideoPause = (index) => {
    console.log(index);
    // TODO
}

<VideoPlayer contents={videoList} onPause={onVideoPause} />

9. onCurrentTimeChange

当前视频播放时间变化时触发的回调函数，可用于实时记录播放进度

属性名：onCurrentTimeChange
类型：function(time: number): void;
是否必须：否
默认值：undefined
示例：

const onCurrentTimeChanged = (time) => {
    console.log(time);
    // TODO
    // 在这里发请求把当前时间传到后端保存，下次打开视频时可以记忆播放位置续播
}

<VideoPlayer contents={videoList} onCurrentTimeChange={onCurrentTimeChanged} />

10. onVolumeChange

音量变化时的回调函数

属性名：onVolumeChange
类型：function(volume: number, muted: boolean): void;
是否必须：否
默认值：undefined
示例：

const onVolumeChanged = (volume, muted) => {
    if(muted){
        console.log('视频静音了');
    }
    else {
        console.log(`视频当前音量为${volume}`);
    }
}

<VideoPlayer contents={videoList} onVolumeChange={onVolumeChanged} />

11. onVideoEnded

当视频播放完成时触发的回调函数

属性名：onVideoEnded
类型：function(index?: number): void;
是否必须：否
默认值：undefined
示例：

const onVideoEnded = (index) => {
    console.log(`索引值为${index}的视频用户已学完`);
    // TODO
}

<VideoPlayer contents={videoList} onVideoEnded={onVideoEnded} />

12. onAllVideoEnded

列表中所有视频播放完成的回调函数

属性名：onAllVideoEnded
类型：function(): void;
是否必须：否
默认值：undefined
示例：

const onAllEnded = () => {
    console.log('恭喜您，本课程所有视频您已学完');
}

<VideoPlayer contents={videoList} onAllVideoEnded={onAllEnded} />