You need to enable JavaScript to run this app.
导航
播放器内核
最近更新时间:2024.04.12 15:38:55首次发布时间:2024.04.12 15:38:55

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;
参数类型读写类型描述
configObject只读当前播放器的配置对象。
rootHTMLElement只读播放器外层容器 DOM 对象
videoObject只读媒体对象,通常是 videoElement/audioElement
autoplayBoolean可读可写设置/返回 自动播放属性
bufferedTimeRange只读返回当前已缓冲的时间范围
playedTimeRange只读返回已经播放的音频/视频的时间范围
crossOriginString可读可写设置/返回是否跨域
currentSrcString可读可写设置/返回当前视频的播放地址
currentTimeNumber可读可写设置/返回视频当前的播放时间,单位:s
durationNumber只读返回视频时长,单位:s
cumulateTimeNumber只读返回视频累计播放时长, 单位:s
volumeNumber可读可写设置/返回视频的音量(0~1)
mutedBoolean可读可写设置/返回视频静音状态
defaultMutedBoolean只读是否默认静音,只在初始化的时候生效
playbackRateNumber可读可写设置/返回当前视频播放倍速
errorMediaError | String只读媒体错误对象,同 player.video.error
errorNoteString只读媒体错误对象常量,同 Media error code constants
loopBoolean可读可写设置/返回是否开启循环播放
srcString可读可写设置/返回当前视频的地址(设置的时候相当于切换当前播放的视频源)
langString可读可写设置/返回当前语言
controlPlugin可读可写播放器控制栏插件对象,具体针对控制栏的说明,可参见 control
innerContainerHTMLElement只读内置容器 DOM 对象,该属性只有在画面和控制栏互不重叠情况下存在,即当配置config.marginControls 为 true 的时候存在

状态属性

参数类型读写类型描述
stateString只读播放器当前所处的状态,所有状态枚举值和说明如下:
枚举名称枚举值描述
ERROR0播放出现错误
INITIAL1初始化
READY2配置/事件/插件等均已经初始化/绑定/实例化完成
ATTACHING3进入媒体对象挂载阶段
ATTACHED4媒体对象已经挂载到了 DOM 中
NOTALLOW5播放被阻止
RUNNING6已经成功起播进入播放流程
ENDED7播放结束
DESTROYED8播放器实例处于已被销毁
endedBoolean只读当前视频是否播放结束。
pausedBoolean只读当前视频是否处于暂停状态。
networkStateString只读视频的网络状态,具体取值列表如下:
枚举名称枚举值描述
NETWORK_EMPTY0目前还没有数据,readyState 的值是 HAVE_NOTHING
NETWORK_IDLE1HTMLMediaElement 处于活动状态并已选择资源,但未使用网络
NETWORK_LOADING2浏览器正在下载 HTMLMediaElement 数据
NETWORK_NO_SOURCE3未找到 HTMLMediaElement src。
readyStateString只读视频的就绪状态,具体取值列表如下:
枚举名称枚举值描述
HAVE_NOTHING0没有关于媒体资源的可用信息
HAVE_METADATA1已检索到足够多的媒体资源来初始化元数据, 快进/快退不会引发异常
HAVE_CURRENT_DATA2当前播放位置的数据可用,但不足以播放下一帧
HAVE_FUTURE_DATA3当前播放位置以及未来至少一小段时间的数据是可用的(至少有两帧以上的数据)
HAVE_ENOUGH_DATA4有足够的数据可用,并且下载速率足够,媒体可以不间断地播放到最后
isFullscreenBoolean只读播放器是否处于全屏状态。
isCssfullScreenBoolean只读播放器是否处于网页全屏状态。
isSeekingBoolean只读是否处于快进/快退状态。
isActiveBoolean只读是否处于焦点状态,处于焦点状态会显示控制栏。

API

play :播放

调用 play(),实现播放功能的代码示例如下:

@return{ Promise<void> | null }

playerSdk.player.play()// OR
playerSdk.player.play().then(() => {// 播放成功}).catch(() => {// 播放失败,一般发生于未经用户交互时的自动播放})

pause:暂停

调用 pause(),实现暂停功能的代码示例如下:

playerSdk.player.pause()

start:启动

启动播放器,开始加载媒体资源,初始化 video 元素。代码示例如下:

@param{ string } url 视频地址。

playerSdk.player.start(url)

replay:重新播放

播放进度返回至片头,重新播放,一般在播放结束时调用。代码示例如下:

playerSdk.player.replay()

seek

调用 seek(),实现跳转到某个时间点继续播放的功能,代码示例如下:

@param{ number } time,参数是 number 类型,单位是s(秒)。

playerSdk.player.seek(20)

reload:重新加载

调用 reload(),实现重新加载的功能,代码示例如下:

playerSdk.player.reload()

resetState():重置状态

重置当前实例状态,暂停视频并且将当前实例状态设置为起播之前的状态,累计播放时长的计算结果会清空,播放器容器 DOM 上的类名会重置为起播之前的状态。

reset():重置

调用 resetState 重置实例状态,并且注销所有已经注册的组件,并且将当前实例的配置恢复为默认值。

setConfig:设置配置项

更新配置信息,如果新的配置列表中包含内置插件的配置项,则会调用内置插件的 setConfig 对其进行更新。代码示例如下:

@param {config)} newConfig

playerSdk.player.setConfig({url: '另一个url',})

destroy:销毁

销毁播放器内核对象,该对象销毁的时候所有内置对象都会销毁,在调用的时候会下发 Events.DESTROY 事件。

注意

  • 播放器内核实例销毁之后,请将播放器内核实例的引用置空,释放内存。
  • 在播放器实例 destroy 之后再调用相关 API 有可能引发错误。
playerSdk.player.destroy() // 销毁播放器
playerSdk.player = null // 将实例引用置空

resetState:还原状态

尝试暂停 MediaElement,并还原播放器 UI 状态。

playerSdk.player.resetState()

focus:获取焦点

播放器获取焦点,调用该 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

blur:失去焦点

播放器失去焦点,调用该 API,playerSdk.player.isActive 将会变为 false,会触发 Events.playerSdk.player_BLUR 事件

@param{ { ignorePaused?: boolean } } data

ignorePaused 是否忽略暂停状态,默认值是 true,默认暂停的时候不取消焦点状态。

canPlayType:检测视频类型

检测当前浏览器是否能播放指定类型的视频,实现的代码示例如下:

  • @param{ string } mimeType 需要检测的MimeType
  • @return{ boolean } 是否可播放
const mimeType = 'video/mp4; codecs="avc1.64001E, mp4a.40.5"'
playerSdk.player.canPlayType(mimeType);

getBufferedRange:获取缓冲时间范围

返回 currentTime 所处的缓冲时间范围,start 表示缓冲起始时间,end 表示缓存截止时间。

  • @param{ TimeRanges? } buffered 如果不传则获取playerSdk.player.buffered
  • @return{ [number, number] } [start, end] 返回缓冲开始时间和结束时间
const [start, end] = playerSdk.player.getBufferedRange();

checkBuffer:验证缓冲区间

验证某个时间点是否在当前缓冲区间内。

  • @param{number} time 时间点
  • @return{ boolean }
const flag = playerSdk.player.checkBuffer(10);

getFullscreen:获取全屏状态

全屏作用的 DOM 节点,如果不传默认是 playerSdk.player.root,必须是 playerSdk.player.root 的父辈节点,如果该接口调用的时候处于网页全屏状态会自动退出网页全屏,下发事件 Events.FULLSCREEN_CHANGE

@param{ HTMlElement? } el

// 监听全屏变化
playerSdk.player.on(Events.FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 全屏} else {// 退出全屏}})// 播放器进入全屏状态
playerSdk.player.getFullscreen()

exitFullscreen:退出全屏状态

全屏作用的 DOM 节点,默认不传会获取 getFullscreen 作用的节点,必须是 playerSdk.player.root 的父辈节点,该接口调用会下发事件 Events.FULLSCREEN_CHANGEisFullscreen 为 false。

@param{ HTMlElement? } el

playerSdk.player.exitFullscreen()

getCssFullscreen:获取网页全屏状态

播放器进入网页全屏,利用CSS模拟实现全屏效果。全屏作用的 DOM 节点,传入参数须是播放器容器playerSdk.player.root 的父辈节点,默认为播放器容器 playerSdk.player.root,如果该接口调用的时候处于全屏状态,会自动退出全屏,下发事件 Events.CSS_FULLSCREEN_CHANGE

@param{ HTMlElement? } el

// 监听网页全屏变化
playerSdk.player.on(Events.CSS_FULLSCREEN_CHANGE, (isFullscreen) => {if (isFullscreen) {// 网页全屏} else {// 退出网页全屏}})
playerSdk.player.getCssFullscreen()

exitCssFullscreen:退出网页全屏状态

全屏作用的 DOM 节点,默认不传会获取 getCssFullscreen 作用的节点, 必须是 playerSdk.player.root 的父辈节点,该接口调用会下发事件 Events.CSS_FULLSCREEN_CHANGE, isFullscreenfalse

@param{ HTMlElement? } el

playerSdk.player.exitCssFullscreen()

addClass:增加类名

给播放器容器 playerSdk.player.root 添加 CSS 类名。

@param{ string } className 类名

playerSdk.player.addClass('className')

removeClass:移除类名

给播放器容器playerSdk.player.root移除 CSS 类名。

@param{ string } className 类名

playerSdk.player.removeClass('className')

hasClass:判定类名

判断播放器容器 playerSdk.player.root 是否存在 CSS 类名。

  • @param{ string } className 类名
  • @return{ boolean }
const flag = playerSdk.player.hasClass('className')

setAttribute:设置属性

给播放器容器 playerSdk.player.root 设置属性

  • @param{ string } key 属性名
  • @param{ string } value
playerSdk.player.setAttribute('key', 'value')

resize:重置尺寸

调整播放器尺寸,如果初始化的时候有配置 fitVideoSize 或者 videoFillMode,或者视频画面做了旋转,调用该 API 会触发整体的尺寸计算,根据视频画面和当前播放器容器尺寸做计算。

playerSdk.player.resize()

getPlugin:获取实例

从当前播放器获取插件的实例,代码示例如下:

@param{ string } pluginName

const pluginInstance = playerSdk.player.getPlugin('pluginName')

registerPlugin:注册插件

在当前播放器上注册某个插件。

  • @param{ {plugin: function, options: object} | function } plugin 插件构造函数。
  • @param{ {[propName: string]: any}? } 可选配置,config 插件配置列表。
  • @return{ object } pluginInstance 返回插件实例。
const pluginInstance = playerSdk.player.registerPlugin(MyPlugin)

unRegisterPlugin:销毁/注销插件

在当前播放器上销毁或者注销某个插件,代码示例如下:

  • @param{ { pluginName: string } | string } Plugin 插件实例或者插件名称。
  • @param{ boolean } removedFromConfig 注销实例的同时,是否同时将其从playerSdk.player.config.plugins 中移除,默认 false
const pluginInstance = playerSdk.player.unRegisterPlugin(pluginName)