竞技学院

西瓜播放器

2025-12-11 13:41:43

# V2-V3升级指南xgplayerV3版本在V2的基础上设计了更加全面的插件化机制，所有的插件都有独立的API、配置信息，并且可以在播放器实例的生命周期中可以任意注销，也可以在实例初始化之后注册一个新的插件; 因为在V3版本中每一个插件都是一个完整的实例，因此你可以通过player.getPlugin(name)来获取插件的实例，进而访问插件的配置、属性以及独立调其开放的API。因为这些新特性的引入，也带来了一些使用的差异，以下我们将对升级过程中遇到的差异进行说明，希望能够对你的升级有一定的指导

# 引用和打包# V2V2版本使用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使用方式

# V3v3版本使用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方式

# 配置# 配置数据类型扩展V3保留的V2中大多数的基础配置，但是将部分和内置插件相关的配置项独立在了以插件为名的命名空间下，避免播放器实例的config对象过于冗余, 因此有一部分原来在playerConfig中的配置项有一些被抽离到了具体的插件中，具体说明如下：

V2配置V3配置备注lastPlayTimestartTime视频起播时间点，默认为0lastPlayTimeHideDelay无无rotateFullscreenfullscreen: { rotateFullscreen: true }抽离为全屏按钮组件的配置项keyShortcut（on/off）keyShortcut(true/false)是否开启快捷键能力keyShortcutStepkeyboard: { seekStep: 10}快捷键快进/快退调整步长,更多快捷键配置execBeforePluginsCall废弃closeVideoTouch废弃v3中移动端手势交互独立出了一个插件mobile,支持了更多的手势配置，手势配置enableVideoDbltouch废弃disableProgressprogress:{ 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事件keyV3事件key备注自动播放被阻止autoplay was preventedEvents.AUTOPLAY_PREVENTED自动播放开始autoplay startedEvents.AUTOPLAY_STARTED进入/退出全屏requestFullscreen/exitFullscreenEvents.FULLSCREEN_CHANGE合并为一个事件，在回调数据中区分是进入还是退出进入/退出网页全屏requestCssFullscreen/exitCssFullscreenEvents.CSS_FULLSCREEN_CHANGE同上进入/退出旋转全屏getRotateFullscreen/exitRotateFullscreenEvents.FULLSCREEN_CHANGE旋转全屏只是全屏的一个变体，不再单独触发进入/退出画中画requestPictureInPicture/exitPictureInPictureEvents.PIP_CHANGE同上除了以上变更，v3也增加了一些包括快捷键触发Events.SHORTCUT、内置UI用户行为Events.USER_ACTION等事件，所有事件的详细解说请参考事件说明和使用

# API和属性# APIV3的API基本保留了V2的API, 只有少数部分有变更，具体变更如下

APIV2调用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列表

# 属性部分变更的属性如下

APIV2调用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

详细说明请看Util, Sniffer

# 扩展插件(即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

更多配置和说明请参考xgplayer-hls

# xgplayer-flv# npm方式V2/**

* V2 npm使用方式

**/

import Player from 'xgplayer'

import FlvPlayer from 'xgplayer-flv'

// 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

更多配置和说明请参考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-musicV2中xgplayer-music(即音乐播放器)是继承于Player对象，这种方式会带来耦合性过高的问题； xgplayer-music本质上是对xgplayer音乐播放能力的扩展，包含一组适用于音乐播放的UI组件和功能扩展，V3将这些功能解耦抽离，并组成了一个音乐播放器preset，具体使用方式如下：

# npm#V2import Player from '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'});

#V3import Player from '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

#V3