V2-V3升级指南
xgplayerV3版本在V2的基础上设计了更加全面的插件化机制，所有的插件都有独立的API、配置信息，并且可以在播放器实例的生命周期中可以任意注销，也可以在实例初始化之后注册一个新的插件; 因为在V3版本中每一个插件都是一个完整的实例，因此你可以通过player.getPlugin(name)来获取插件的实例，进而访问插件的配置、属性以及独立调其开放的API。因为这些新特性的引入，也带来了一些使用的差异，以下我们将对升级过程中遇到的差异进行说明，希望能够对你的升级有一定的指导
引用和打包
V2
V2版文使用webpack打包，整个包只提供了压缩后的index文件，css是行内加载模式，直接打包在了js文件中，这样的打包也带来了在npm引用的方式下，无法灵活的按需打包、在ssr环境下import语句会在因为css行内加载问题在server端报错等问题, 其打包目录如下
├── browser # umd打包路径，用于浏览器下直接引用
│ ├── index.js
│── dist
│ ├── index.js # npm下默认引用路径
│── es # es文件路径需要自行引入
...
│── types #d.ts声明文件
npm方式
import Player from 'xgplayer'
const player = new Player({...})
CDN使用方式
<script src="//unpkg.byted-static.com/xgplayer/2.31.2/browser/index.js" charset="utf-8"></script>
<script type="text/javascript">
var player = new Player({
...
})
</script>
V3
v3版本使用rollup打包, css文件和js文件分离，解决SSR报错问题，删除了browser目录， 只提供dist和es两个目录，类型声明文件在es目录中全部有生成，不再独立文件夹；提供CHANGELOG.md文件，以下为这个包的路径
├── dist # umd打包路径，用于浏览器下直接引用或者是SSR的时候node端的入口
│ ├── index.min.js # 默认preset的打包文件，
│ ├── index.min.css # 压缩后的css独立文件
│── es # npm下默认引用路径
│ ├── index.js
│ ├── ...
npm方式
import Player from 'xgplayer'
// 需要独立引用是css文件
import 'xgplayer/dist/index.min.css'
const player = new Player({...})
CDN方式
<!--单独引用css文件-->
<link rel="stylesheet" href="https://unpkg.byted-static.com/xgplayer/3.0.0-next.42/dist/index.min.css">
<script src="https://unpkg.byted-static.com/xgplayer/3.0.0-next.42/dist/index.min.js" charset="utf-8"></script>
<script type="text/javascript">
var player = new Player({
...
})
</script>
配置
配置数据类型扩展
V3保留的V2中大多数的基础配置，但是将部分和内置插件相关的配置项独立在了以插件为名的命名空间下，避免播放器实例的config对象过于冗余, 因此有一部分原来在playerConfig中的配置项有一些被抽离到了具体的插件中， 具体说明如下：
| V2配置 | V3配置 | 备注 |
|---|---|---|
| lastPlayTime | startTime | 视频起播时间点，默认为0 |
| lastPlayTimeHideDelay | 无 | 无 |
| rotateFullscreen | fullscreen: { rotateFullscreen: true } | 抽离为全屏按钮组件的配置项 |
| keyShortcut（on/off） | keyShortcut(true/false) | 是否开启快捷键能力 |
| keyShortcutStep | keyboard: { seekStep: 10} | 快捷键快进/快退调整步长,更多快捷键配置 |
| execBeforePluginsCall | 废弃 | |
| closeVideoTouch | 废弃 | v3中移动端手势交互独立出了一个插件mobile,支持了更多的手势配置，手势配置 |
| enableVideoDbltouch | 废弃 | |
| disableProgress | progress:{ closeMoveSeek: true } | 进度条组件支持了更细化的配置，进度条配置 |
| allowSeekPlayed | 废弃 | 进度条提供了丰富的hook功能，能够实现更灵活的功能，详情请看进度条配置 |
| allowPlayAfterEnded | 废弃 | 同上 |
| closeInactive | 废弃 | 控制栏独立插件，可以通过controls: { autoHide: false }, 详情请看 控制栏 |
除了以上有变更的配置，V3将所有和内置插件相关的配置都抽离到插件自己的配置中，所以会有类似如下的使用方式：
插件配置例如playerConfig.volume这个配置项，既可以是数字表示默认音量，也可以是object表示整个音量调节插件的配置，如下
new Player({
...,
volume: 0.6 // 起播默认音量是0.6
})
// Object类型
new Player({
// 此时是整个内置的音量控制条的配置
volume: {
default: 0.6, // 默认音量0.6，
showValueLabel: true // 是否在音量控制条顶部显示音量百分比
}
})
类似这种扩展的还有 progress， controls, fullscreen, start等具体配合可以参考 内置插件。
按钮图标配置
v2中部分插件为了提供按钮的可配置性，提供了类似playerConfig.playBtn这种类型的按钮配置项，但是并不是所有的按钮都可配置，V3中抽离了所有的按钮配置，使用方式说明如下：
// v2中配置右侧播放按钮
new Player({
playBtn: xxx
})
/**
* v3中所有按钮全部抽离为icons配置
*/
new Player({
icons: {
play: xxx, // 数据格式为返回dom的匿名函数、html格式的string、或者dom对象
pause: xxx
}
})
关于所有的内置插件icon图标配置，更多详情参考内置插件icons配置
事件
v3将所有的事件的白名单均整合在了src/events.js件中，你可以在这个文件中拿到所有支持的事件名称，使用如下
import Player, { Events } from 'xgplayer'
import 'xgplayer/dist/index.min.css'
const player = new Player({...})
player.on(Events.PLAY, () => {
// ...
})
其中有以下几个事件有变更
| 事件名 | V2事件key | V3事件key | 备注 |
|---|---|---|---|
| 自动播放被阻止 | autoplay was prevented | Events.AUTOPLAY_PREVENTED | |
| 自动播放开始 | autoplay started | Events.AUTOPLAY_STARTED | |
| 进入/退出全屏 | requestFullscreen/ exitFullscreen | Events.FULLSCREEN_CHANGE | 合并为一个事件， 在回调数据中区分是进入还是退出 |
| 进入/退出网页全屏 | requestCssFullscreen/ exitCssFullscreen | Events.CSS_FULLSCREEN_CHANGE | 同上 |
| 进入/退出旋转全屏 | getRotateFullscreen/ exitRotateFullscreen | Events.FULLSCREEN_CHANGE | 旋转全屏只是全屏的一个变体，不再单独触发 |
| 进入/退出画中画 | requestPictureInPicture/ exitPictureInPicture | Events.PIP_CHANGE | 同上 |
除了以上变更，v3也增加了一些包括快捷键触发Events.SHORTCUT、内置UI用户行为Events.USER_ACTION等事件，所有事件的详细解说请参考事件说明和使用
API和属性
API
V3的API基本保留了V2的API, 只有少数部分有变更，具体变更如下
| API | V2调用 | V3调用 | 备注 |
|---|---|---|---|
| 进入迷你播放器 | player.getMiniplayer() | player.plugins.miniscreen.getMini() | |
| 退出迷你播放器 | player.exitMiniplayer() | player.plugins.miniscreen.extMini() | |
| 添加插件 | install | 删除 | 初始化之前config.plugins 配置需要组装的插件； 实例化之后可以调用非player.registerPlugin 来注册新的插件 |
| 更新配置 | 无 | player.setConfig(newConfig) | 这个API作用是可以通过config命名空间更新内置插件的配置 |
| 切换播放另一个视频 | 无/ | player.playNext(newConfig) | v3提供的playNext，不仅仅是切换当前播放的视频源， 还会重置内部的累计播放时长等数据， 并且可以根据新的配置项更新所有的内置插件状态 |
除了以上变更，还新增了其他使用的API, 详细说明请看API列表
属性
部分变更的属性如下
| API | V2调用 | V3调用 | 备注 |
|---|---|---|---|
| networkState | 返回视频的当前网络状态对应文本 | 返回的是网络状态对应的数字 | |
| readyState | 返回视频的就绪状态文本 | 返回视频的就绪状态对应的数字 | |
| controls | 返回的控制栏dom | 返回的是控制栏插件对象 | |
| bullet | 播放器弹幕是否开启 | 删除，通过弹幕插件读取状态 | |
| textTrack | 播放器外挂字幕是否开启 | 删除，通过外挂字幕插件获取状态 | |
| lang | 无 | 当前语言 | 该属性是个存取器，修改语言的时候支持内置UI插件同步更新语言 |
除了以上变更，还新增了其他使用的API, 详细说明请看属性列表
内置工具类（util、sniffer）
在播放器中我们有一些公共工具util的封装和浏览器环境sniffer的封装，这些工具类的名称全部变更为大写开头,如下
/**
* npm v2使用方式
*/
import Player from 'xgplayer'
const ifHas = Player.util.hasClass('xxx')
const device = Player.sniffer.device
/**
* npm v3使用方式
*/
import Player from 'xgplayer'
const ifHas = Player.Util.hasClass('xxx')
const device = Player.Sniffer.device
// or
import { Util, Sniffer } from 'xgplayer'
const ifHas = Util.hasClass('xxx')
const device = Sniffer.device
扩展插件(即hls/flv等插件)
在v2中支持hls、flv等格式的播放都是使用一个集成了xgplayer的新的构造函数去生成，这样使用代码耦合性很高，无法在同一个实例下切换播放格式； v3将这些格式的支持都处理成为了可插拔的插件，这些插件可以随时注册或者注销，具体使用差别如下
hls
npm方式
- V2
/**
* V2 npm使用方式
**/
import Player from 'xgplayer'
import HlsPlayer from 'xgplayer-hls'
// HlsPlayer继承于xgplayer
const player = new HlsPlayer({
id:'dom-id',
isLive: true,
url: 'test.m3u8',
})
- V3
/**
* V3 npm使用方式
**/
import Player from 'xgplayer'
import HlsPlugin from 'xgplayer-hls'
import "xgplayer/dist/index.min.css"
const player = new Player({
id:'dom-id',
isLive: true,
plugins: [HlsPlugin], // 以xgplayer的插件形式传入并挂载
url: 'test.m3u8',
...
})
CDN 方式
- V2
<script src="//unpkg.byted-static.com/xgplayer/@latest/browser/index.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-hls/@latest/dist/index.min.js"></script>
<script>
var player = new HlsPlayer({
id:'dom-id',
isLive: true，
...
})
</script>
- V3
<link rel="stylesheet" href="//unpkg.byted-static.com/xgplayer/@latest/dist/index.min.css"/>
<script src="//unpkg.byted-static.com/xgplayer/@latest/dist/index.min.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-hls/@latest/dist/index.min.js"></script>
<script>
var player = new Player({
id:'dom-id',
isLive: true,
plugins: [window.HlsPlayer]
})
</script>
更多配置和说明请参考xgplayer-hls
xgplayer-flv
npm方式
- V2
/**
* V2 npm使用方式
**/
import Player from 'xgplayer'
import FlvPlayer from 'xgplayer-hls'
// FlvPlayer继承于xgplayer
const player = new FlvPlayer({
id:'dom-id',
isLive: true,
url: 'test.flv',
})
- V3
/**
* V3 npm使用方式
**/
import Player from 'xgplayer'
import FlvPlugin from 'xgplayer-flv'
import "xgplayer/dist/index.min.css"
const player = new Player({
id:'dom-id',
isLive: true,
plugins: [FlvPlugin], // 以xgplayer的插件形式传入并挂载
url: 'test.m3u8',
...
})
CDN 方式
- V2
<script src="//unpkg.byted-static.com/xgplayer/@latest/browser/index.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-flv/@latest/dist/index.min.js"></script>
<script>
var player = new FlvPlayer({
id:'dom-id',
isLive: true，
...
})
</script>
- V3
<link rel="stylesheet" href="//unpkg.byted-static.com/xgplayer/@latest/dist/index.min.css"/>
<script src="//unpkg.byted-static.com/xgplayer/@latest/dist/index.min.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-flv/@latest/dist/index.min.js"></script>
<script>
var player = new Player({
id:'dom-id',
isLive: true,
plugins: [window.FlvPlayer]
})
</script>
更多配置和说明请参考xgplayer-flv
内置插件
v2中默认导出的Player对象会集成弹幕danmu和外挂字幕texttrack插件，V3考虑到这两个插件不是常用插件，且都依赖第三方包，为了减少代码的冗余，这两个插件不会在默认preset中引用，需要使用的话，要自行import， 具体使用方式如下：
弹幕
import Player from 'xgplayer'
import "xgplayer/dist/index.min.css"
import Danmu from 'xgplayer/es/plugins/danmu'
import "xgplayer/es/plugins/danmu/index.css"
const player = new Player({
...,
plugins: [Danmu]
})
Notice
CDN方式引用不支持使用弹幕
外挂字幕
import Player from 'xgplayer'
import "xgplayer/dist/index.min.css"
import TextTrack from 'xgplayer/es/plugins/track'
import "xgplayer/es/plugins/track/index.css"
const player = new Player({
...,
plugins: [TextTrack]
})
Notice
CDN方式引用不支持使用字幕
xgplayer-music
V2中xgplayer-music(即音乐播放器)是继承于Player对象，这种方式会带来耦合性过高的问题； xgplayer-music本质上是对xgplayer音乐播放能力的扩展，包含一组适用于音乐播放的UI组件和功能扩展，V3将这些功能解耦抽离，并组成了一个音乐播放器preset，具体使用方式如下：
npm
V2
import Player 'xgplayer';
// MusicPlayer继承于xgplayer
import MusicPlayer from 'xgplayer-music';
const player = new MusicPlayer({
...
})
// 频谱初始化，频谱的初始化和MusicPlayer高度耦合，无法单独使用
var an = player.analyze(document.querySelector('canvas'))
an.style = {
bgColor: '#c8c8c8',
color: '#909099'
}
// 向播放列表中添加歌曲
player.add({src:'url', name:'name'});
V3
import Player 'xgplayer';
import MusicPreset, { Analyze } from 'xgplayer-music';
import "xgplayer/dist/index.min.css"
import "xgplayer-music/dist/index.min.css"
const player = new Player({
...,
presets: [MusicPreset] // 如果需要继承默认的preset,则转入值为 ['default', MusicPreset]
})
// 频谱初始化，频谱和music解耦，可以在不使用music的情况下单独使用
const analyze = Analyze(player, document.querySelector('canvas'), {
bgColor: 'rgba(0,0,0,0.7)',
stroke: 3
})
// 向播放列表中添加歌曲
player.plugins.music.add({src:'url', name:'name', vid: 'xxx', poster: ''});
其余和音乐播放相关的API全部集成到了music插件中，更多说明见音乐播放器
CDN方式
V2
<script src="//unpkg.byted-static.com/xgplayer/2.31.2/browser/index.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-music/2.1.7/browser/index.js"></script>
<script>
var player = new window.Music({
...
})
// 频谱初始化
var an = player.analyze(document.querySelector('canvas'))
an.style = {
bgColor: '#c8c8c8',
color: '#909099'
}
</script>
V3
<link rel="stylesheet" href="https://unpkg.byted-static.com/xgplayer/@latest/dist/index.min.css">
<link rel="stylesheet" href="https://unpkg.byted-static.com/xgplayer-music/@latest/dist/index.min.css">
<script src="//unpkg.byted-static.com/xgplayer/@latest/dist/index.min.js"></script>
<script src="//unpkg.byted-static.com/xgplayer-music/@latest/dist/index.min.js"></script>
<script>
var player = new window.Player({
...,
presets: [MusicPreset] // 如果需要继承默认的preset,则转入值为 ['default', MusicPreset]
})
// 频谱初始化
var analyze = new MusicPreset.Analyze(player, document.querySelector('canvas'), {
bgColor: 'rgba(0,0,0,0.7)',
stroke: 3
})
</script>