SDK 实例的播放功能是由播放器内核提供,播放器内核提供以下属性、API 等,供您自行开发实现灵活的播放功能。
获取播放器内核和调用 API 的示例代码如下所示。
const playerSdk = new VePlayer({ id: 'video', width: 800, height: 500, url: 'xx.mp4' }); // 获取属性:当前播放时间 const curTime = playerSdk.player.currentTime; // 获取状态属性:当前视频是否处于暂停状态 const isPaused = playerSdk.player.paused; // 调用 API:播放视频 playerSdk.player.play().then(() => { // 播放成功 }).catch(() => { // 播放失败,一般发生于未经用户交互时的自动播放 });
播放器内核的属性大部分是只读类型的,某些属性还支持写入。以获取视频时长 duration
为例,该属性是只读类型,不能通过 set 方式设置视频时长。而视频音量 volume
不仅支持播放器内核对象 get 方式获取,还支持 set 方式设置音量。
const playerSdk = new VePlayer({ id: 'video', width: 800, height: 500, url: 'xx.mp4' }); // 获取视频时长 const duration = playerSdk.player.duration; // 获取视频音量 const curVolume = playerSdk.player.volume; // 设置音量 playerSdk.player.volume = 0.1;
参数 | 类型 | 读写类型 | 描述 |
---|---|---|---|
config | Object | 只读 | 当前播放器的配置对象。 |
root | HTMLElement | 只读 | 播放器外层容器 DOM 对象 |
video | Object | 只读 | 媒体对象,通常是 videoElement/audioElement |
autoplay | Boolean | 可读可写 | 设置/返回 自动播放属性 |
buffered | TimeRange | 只读 | 返回当前已缓冲的时间范围 |
played | TimeRange | 只读 | 返回已经播放的音频/视频的时间范围 |
crossOrigin | String | 可读可写 | 设置/返回是否跨域 |
currentSrc | String | 可读可写 | 设置/返回当前视频的播放地址 |
currentTime | Number | 可读可写 | 设置/返回视频当前的播放时间,单位:s |
duration | Number | 只读 | 返回视频时长,单位:s |
cumulateTime | Number | 只读 | 返回视频累计播放时长, 单位:s |
volume | Number | 可读可写 | 设置/返回视频的音量(0~1) |
muted | Boolean | 可读可写 | 设置/返回视频静音状态 |
defaultMuted | Boolean | 只读 | 是否默认静音,只在初始化的时候生效 |
playbackRate | Number | 可读可写 | 设置/返回当前视频播放倍速 |
error | MediaError | String | 只读 |
errorNote | String | 只读 | 媒体错误对象常量,同 Media error code constants |
loop | Boolean | 可读可写 | 设置/返回是否开启循环播放 |
src | String | 可读可写 | 设置/返回当前视频的地址(设置的时候相当于切换当前播放的视频源) |
lang | String | 可读可写 | 设置/返回当前语言 |
control | Plugin | 可读可写 | 播放器控制栏插件对象,具体针对控制栏的说明,可参见 control |
innerContainer | HTMLElement | 只读 | 内置容器 DOM 对象,该属性只有在画面和控制栏互不重叠情况下存在,即当配置config.marginControls 为 true 的时候存在 |
参数 | 类型 | 读写类型 | 描述 | ||
---|---|---|---|---|---|
state | String | 只读 | 播放器当前所处的状态,所有状态枚举值和说明如下: | ||
枚举名称 | 枚举值 | 描述 | |||
ERROR | 0 | 播放出现错误 | |||
INITIAL | 1 | 初始化 | |||
READY | 2 | 配置/事件/插件等均已经初始化/绑定/实例化完成 | |||
ATTACHING | 3 | 进入媒体对象挂载阶段 | |||
ATTACHED | 4 | 媒体对象已经挂载到了 DOM 中 | |||
NOTALLOW | 5 | 播放被阻止 | |||
RUNNING | 6 | 已经成功起播进入播放流程 | |||
ENDED | 7 | 播放结束 | |||
DESTROYED | 8 | 播放器实例处于已被销毁 | |||
ended | Boolean | 只读 | 当前视频是否播放结束。 | ||
paused | Boolean | 只读 | 当前视频是否处于暂停状态。 | ||
networkState | String | 只读 | 视频的网络状态,具体取值列表如下: | ||
枚举名称 | 枚举值 | 描述 | |||
NETWORK_EMPTY | 0 | 目前还没有数据,readyState 的值是 | |||
NETWORK_IDLE | 1 | HTMLMediaElement 处于活动状态并已选择资源,但未使用网络 | |||
NETWORK_LOADING | 2 | 浏览器正在下载 HTMLMediaElement 数据 | |||
NETWORK_NO_SOURCE | 3 | 未找到 HTMLMediaElement src。 | |||
readyState | String | 只读 | 视频的就绪状态,具体取值列表如下: | ||
枚举名称 | 枚举值 | 描述 | |||
HAVE_NOTHING | 0 | 没有关于媒体资源的可用信息 | |||
HAVE_METADATA | 1 | 已检索到足够多的媒体资源来初始化元数据, 快进/快退不会引发异常 | |||
HAVE_CURRENT_DATA | 2 | 当前播放位置的数据可用,但不足以播放下一帧 | |||
HAVE_FUTURE_DATA | 3 | 当前播放位置以及未来至少一小段时间的数据是可用的(至少有两帧以上的数据) | |||
HAVE_ENOUGH_DATA | 4 | 有足够的数据可用,并且下载速率足够,媒体可以不间断地播放到最后 | |||
isFullscreen | Boolean | 只读 | 播放器是否处于全屏状态。 | ||
isCssfullScreen | Boolean | 只读 | 播放器是否处于网页全屏状态。 | ||
isSeeking | Boolean | 只读 | 是否处于快进/快退状态。 | ||
isActive | Boolean | 只读 | 是否处于焦点状态,处于焦点状态会显示控制栏。 |
调用 play()
,实现播放功能的代码示例如下:@return
{ Promise<void> | null }
playerSdk.player.play()// OR playerSdk.player.play().then(() => {// 播放成功}).catch(() => {// 播放失败,一般发生于未经用户交互时的自动播放})
调用 pause()
,实现暂停功能的代码示例如下:
playerSdk.player.pause()
启动播放器,开始加载媒体资源,初始化 video
元素。代码示例如下:@param
{ string } url
视频地址。
playerSdk.player.start(url)
播放进度返回至片头,重新播放,一般在播放结束时调用。代码示例如下:
playerSdk.player.replay()
调用 seek()
,实现跳转到某个时间点继续播放的功能,代码示例如下:@param
{ number } time
,参数是 number 类型,单位是s(秒)。
playerSdk.player.seek(20)
调用 reload()
,实现重新加载的功能,代码示例如下:
playerSdk.player.reload()
重置当前实例状态,暂停视频并且将当前实例状态设置为起播之前的状态,累计播放时长的计算结果会清空,播放器容器 DOM 上的类名会重置为起播之前的状态。
调用 resetState
重置实例状态,并且注销所有已经注册的组件,并且将当前实例的配置恢复为默认值。
更新配置信息,如果新的配置列表中包含内置插件的配置项,则会调用内置插件的 setConfig
对其进行更新。代码示例如下:@param
{config)} newConfig
playerSdk.player.setConfig({url: '另一个url',})
销毁播放器内核对象,该对象销毁的时候所有内置对象都会销毁,在调用的时候会下发 Events.DESTROY
事件。
注意
playerSdk.player.destroy() // 销毁播放器 playerSdk.player = null // 将实例引用置空
尝试暂停 MediaElement
,并还原播放器 UI 状态。
playerSdk.player.resetState()
播放器获取焦点,调用该 API,playerSdk.player.isActive
将会变为 true
,会触发 Events.playerSdk.player_FOCUS
事件。@param
{ { autoHide?: boolean, delay?: number } } data
autoHide
是否需要自动隐藏,默认为true
,即经过delay
时长之后,会自动调用playerSdk.player.blur()
delay
自动隐藏延迟时长,单位 ms,当 autoHide: false
的时候,忽略该配置项,默认取 playerSdk.player.config.inactive
播放器失去焦点,调用该 API,playerSdk.player.isActive
将会变为 false
,会触发 Events.playerSdk.player_BLUR
事件@param
{ { ignorePaused?: boolean } } data
ignorePaused
是否忽略暂停状态,默认值是 true
,默认暂停的时候不取消焦点状态。
检测当前浏览器是否能播放指定类型的视频,实现的代码示例如下:
@param
{ string } mimeType
需要检测的MimeType@return
{ boolean }
是否可播放const mimeType = 'video/mp4; codecs="avc1.64001E, mp4a.40.5"' playerSdk.player.canPlayType(mimeType);
返回 currentTime 所处的缓冲时间范围,start 表示缓冲起始时间,end 表示缓存截止时间。
@param
{ TimeRanges? } buffered
如果不传则获取playerSdk.player.buffered@return
{ [number, number] }
[start, end] 返回缓冲开始时间和结束时间const [start, end] = playerSdk.player.getBufferedRange();
验证某个时间点是否在当前缓冲区间内。
@param
{number} time
时间点@return
{ boolean }
const flag = playerSdk.player.checkBuffer(10);
全屏作用的 DOM 节点,如果不传默认是 playerSdk.player.root,必须是 playerSdk.player.root 的父辈节点,如果该接口调用的时候处于网页全屏状态会自动退出网页全屏,下发事件 Events.FULLSCREEN_CHANGE
。@param
{ HTMlElement? } el
// 监听全屏变化 playerSdk.on(Events.FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 全屏} else {// 退出全屏}})// 播放器进入全屏状态 playerSdk.player.getFullscreen()
全屏作用的 DOM 节点,默认不传会获取 getFullscreen
作用的节点,必须是 playerSdk.player.root 的父辈节点,该接口调用会下发事件 Events.FULLSCREEN_CHANGE
,isFullscreen
为 false。@param
{ HTMlElement? } el
playerSdk.player.exitFullscreen()
播放器进入网页全屏,利用 CSS 模拟实现全屏效果。全屏作用的 DOM 节点,传入参数须是播放器容器 playerSdk.player.root 的父辈节点,默认为播放器容器 playerSdk.player.root,如果该接口调用的时候处于全屏状态,会自动退出全屏,下发事件 Events.CSS_FULLSCREEN_CHANGE
。@param
{ HTMlElement? } el
// 监听网页全屏变化 playerSdk.on(Events.CSS_FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 网页全屏} else {// 退出网页全屏}}) playerSdk.player.getCssFullscreen()
全屏作用的 DOM 节点,默认不传会获取 getCssFullscreen
作用的节点, 必须是 playerSdk.player.root
的父辈节点,该接口调用会下发事件 Events.CSS_FULLSCREEN_CHANGE
, isFullscreen
为 false
。@param
{ HTMlElement? } el
playerSdk.player.exitCssFullscreen()
给播放器容器 playerSdk.player.root
添加 CSS 类名。@param
{ string } className
类名
playerSdk.player.addClass('className')
给播放器容器playerSdk.player.root
移除 CSS 类名。@param
{ string } className
类名
playerSdk.player.removeClass('className')
判断播放器容器 playerSdk.player.root
是否存在 CSS 类名。
@param
{ string } className
类名@return
{ boolean }
const flag = playerSdk.player.hasClass('className')
给播放器容器 playerSdk.player.root
设置属性
@param
{ string } key
属性名@param
{ string } value
值playerSdk.player.setAttribute('key', 'value')
调整播放器尺寸,如果初始化的时候有配置 fitVideoSize
或者 videoFillMode
,或者视频画面做了旋转,调用该 API 会触发整体的尺寸计算,根据视频画面和当前播放器容器尺寸做计算。
playerSdk.player.resize()
从当前播放器获取插件的实例,代码示例如下:@param
{ string } pluginName
const pluginInstance = playerSdk.player.getPlugin('pluginName')
在当前播放器上注册某个插件。
@param
{ {plugin: function, options: object} | function } plugin
插件构造函数。@param
{ {[propName: string]: any}? }
可选配置,config 插件配置列表。@return
{ object } pluginInstance
返回插件实例。const pluginInstance = playerSdk.player.registerPlugin(MyPlugin)
在当前播放器上销毁或者注销某个插件,代码示例如下:
@param
{ { pluginName: string } | string } Plugin
插件实例或者插件名称。@param
{ boolean } removedFromConfig
注销实例的同时,是否同时将其从playerSdk.player.config.plugins 中移除,默认 false
。const pluginInstance = playerSdk.player.unRegisterPlugin(pluginName)