API

提示

本节API代码均默认基于如下环境

import Player, { Events } from 'xgplayer'

const player =  new Player({...})

play

@return{ Promise<void> | null }

播放

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

pause

暂停

player.pause()

start

@param{ string } url 视频地址

启动播放器，开始加载媒体资源，初始化video元素

注意

不建议手动调用，该API对外有废弃可能。推荐根据场景配置autoplay和videoInit

player.start(url)

replay

播放器返回至片头，重新播放，一般在播放结束时调用（对于直播场景无效）

player.replay()

seek

@param{ number } time

跳转到某个时间点继续播放，参数是number类型，单位是s(秒)（对于直播场景无效）

player.seek(20)

reload

重新加载视频

player.reload()

resetState()

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

reset()

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

setConfig

@param {config} newConfig

更新配置信息，如果新的配置列表中包含内置插件的配置项，则会调用内置插件的setConfig对其进行更新

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

playNext(newConfig)

切换播放源

注意

该API为切换播放源的一种方式，内部实现了如下功能：

重置播放器状态: player.resetState()
根据涵参 config 更新播放器及插件配置，比如 newConfig 配置属性中的 url 会将当前 player.config 重置为新入参的配置项
启动播放（切换之前不论是否为暂停状态均启播）

player.playNext({
  url: '另一个url',
  poster: '新的海报图'，
  ...
})

switchURL

@param{string} src
@param{boolean?} seamless 切视频时无缝切换，不产生黑场。只在某些插件实现了该行为才起作用（比如 xgplayer-flv）

切换播放源

提示

该API为切换播放源的一种方式，内部实现了两个功能：

为播放器设置src， player.src = src
根据切换前的播放状态，如果是播放中则在合适时机启动播放

player.switchURL('url')

changeDefinition

@typedef { { url: any, definition: any, [propName: string]: any } } IDefinition

@param{ IDefinition } to
@param{ IDefinition? } from

切换清晰度，具体用法可参考 definition 插件

player.changeDefinition({
  url: '另一个url',
  definition: 1，
  ...
})

destroy

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

注意

播放器实例销毁之后，请将播放实例的引用置空，释放内存
在实例destroy之后再调用相关api有可能引发错误

player.destroy() // 销毁播放器
player = null // 将实例引用置空

resetState

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

player.resetState()

on

@param{ string } event 事件名称，具体事件列表请看Events
@param{ function? } callback

添加事件监听

const boundFunc = () => {
  // Do sth after play event
}
player.on(Events.PlAY, boundFunc)

off

解除事件监听

@param{ string } event 事件名称，具体事件列表请看Events
@param{ function } callback

player.off(Events.PlAY, boundFunc)

emit

@param{ string } event 事件名称，具体事件列表请看Events
@param{ object } data

触发事件

// Customize an error situation and emit event
player.emit(Events.ERROR, {})

focus

@param{ { autoHide?: boolean, delay?: number } } data
- autoHide 是否需要自动隐藏，默认为true，即经过delay时长之后，会自动调用player.blur()
- delay 自动隐藏延迟时长，单位ms，当autoHide: false的时候，忽略该配置项，默认取player.config.inactive

播放器获取焦点，调用该api，player.isActive将会变为true，会触发Events.PLAYER_FOCUS事件

blur

@param{ { ignorePaused?: boolean } } data
- ignorePaused 是否忽略暂停状态，默认值是true，默认暂停的时候不取消焦点状态

播放器失去焦点，调用该api，player.isActive将会变为false，会触发Events.PLAYER_BLUR事件

canPlayType

@param{ string } mimeType 需要检测的MimeType
@return{ boolean } 是否可播放

检测当前浏览器是否能播放指定类型的视频

const mimeType = 'video/mp4; codecs="avc1.64001E, mp4a.40.5"'
player.canPlayType(mimeType);

getBufferedRange

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

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

const [start, end] = player.getBufferedRange();

checkBuffer

@param{number} time 时间点
@return{ boolean }

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

const flag = player.checkBuffer(10);

getFullscreen

@param{ HTMlElement? } el

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

// 监听全屏变化
player.on(Events.FULLSCREEN_CHANGE, (isFullscreen) => {
  if (isFullscreen) {
    // 全屏
  } else {
    // 退出全屏
  }
})

// 播放器进入全屏状态
player.getFullscreen()

exitFullscreen

@param{ HTMlElement? } el 全屏作用的DOM节点，默认不传会获取getFullscreen作用的节点，必须是player.root的父辈节点，该接口调用会下发事件Events.FULLSCREEN_CHANGE，isFullscreen为false

播放器退出全屏状态

player.exitFullscreen()

getCssFullscreen

@param{ HTMlElement? } el 全屏作用的DOM节点，传入参数须是播放器容器player.root的父辈节点（默认为播放器容器player.root），如果该接口调用的时候处于全屏状态，会自动退出全屏，下发事件Events.CSS_FULLSCREEN_CHANGE

播放器进入网页全屏，利用CSS模拟实现全屏效果

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

exitCssFullscreen

@param{ HTMlElement? } el 全屏作用的DOM节点,默认不传会获取getCssFullscreen作用的节点, 必须是player.root的父辈节点，该接口调用会下发事件Events.CSS_FULLSCREEN_CHANGE, isFullscreen为false

播放器退出网页全屏

player.exitCssFullscreen()

addClass

@param{ string } className 类名

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

player.addClass('className')

removeClass

@param{ string } className 类名

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

player.removeClass('className')

hasClass

@param{ string } className 类名
@return{ boolean }

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

const flag = player.hasClass('className')

setAttribute

@param{ string } key 属性名
@param{ string } value 值

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

player.setAttribute('key', 'value')

resize

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

player.resize()

getPlugin

@param{ string } pluginName

从当前播放器获取插件的实例

const pluginInstance = player.getPlugin('pluginName')

registerPlugin

@param{ {plugin: function, options: object} | function } plugin 插件构造函数
@param{ {[propName: string]: any}? } 可选配置，config 插件配置列表
@return{ object } pluginInstance 返回插件实例

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

const pluginInstance = player.registerPlugin(MyPlugin)

unRegisterPlugin

@param{ { pluginName: string } | string } Plugin 插件实例或者插件名称
@param{ boolean } removedFromConfig 注销实例的同时，是否同时将其从player.config.plugins中移除，默认false

在当前播放器上销毁/注销某个插件

const pluginInstance = player.unRegisterPlugin(pluginName)

usePluginHooks

@param{ string } pluginName 插件名称
@param{ string } hookName 预定义的hook名称
@param{ function } handler 具体执行逻辑

启用某个插件的某个hook, hook详细说明请看Hooks

function errorRetry(plugin, ...args) {
  console.log('errorRetry hook')
}
player.usePluginHooks('error', 'errorRetry', errorRetry)

removePluginHooks

@param{ string } pluginName 插件名称
@param{ string } hookName 预定义的hook名称
@param{ function } handler 具体执行逻辑

移除某个插件的某个hook, hook详细说明请看Hooks

function errorRetry(plugin, ...args) {
  console.log('errorRetry hook')
}
player.removePluginHooks('error', 'errorRetry', errorRetry)

useHooks

@param{ string } hookName 预定义的hook名称
@param{ function } handler 具体执行逻辑

启用播放器的某个hook, hook详细说明请看Hooks

注意

该功能属于高级功能，供一些高级扩展插件，例如支持hls/flv播放等插件实现功能使用，非特殊情况最好不要使用
如果想要在交互行为之前做操作，请参考usePluginHooks接口

const playHook = （player, ...args） => {
  // todo
}
player.useHooks('play', playHook)

removeHooks

@param{ string } hookName 预定义的hook名称
@param{ function } handler 具体执行逻辑

移除播放器的某个hook, hook详细说明请看Hooks

const playHook = （player, ...args） => {
  // todo
}
player.removeHooks('play', playHook)

attachVideoEvents

@param{ HTMLVideoElement | HTMLAudioElement | 自定义媒体对象 } video 媒体对象

给播放器挂载一个媒体对象，并注册相应事件

const video = document.createElement('video')
player.attachVideoEvents(video)

detachVideoEvents

@param{ (HTMLVideoElement | HTMLAudioElement | 自定义媒体对象)? } video 媒体对象

给播放器解除媒体对象，并移除相应事件，参数不传入则获取现有的player.video

player.detachVideoEvents()

setEventsMiddleware

@param{ { [propName: string]: function } } middlewares 中间件列表

设置媒体事件中间件，中间件在相关事件emit之前执行，可以阻止某个事件的下发，详情请看EventsMiddleware

注意

该功能属于高级功能，一般情况不需要使用，直接监听事件即可

const middlewares = {
  play: () => {
    console.log('play middleware')
  },
  pause: () => {
    console.log('pause middleware')
  }
}
player.setEventsMiddleware(middlewares)

removeEventsMiddleware

@param{ { [propName: string]: function } } middlewares 中间件列表

移除媒体事件中间件

player.removeEventsMiddleware(middlewares)

西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

# API

# play

# pause

# start

# replay

# seek

# reload

# resetState()

# reset()

# setConfig

# playNext(newConfig)

# switchURL

# changeDefinition

# destroy

# resetState

# on

# off

# emit

# focus

# blur

# canPlayType

# getBufferedRange

# checkBuffer

# getFullscreen

# exitFullscreen

# getCssFullscreen

# exitCssFullscreen

# addClass

# removeClass

# hasClass

# setAttribute

# resize

# getPlugin

# registerPlugin

# unRegisterPlugin

# usePluginHooks

# removePluginHooks

# useHooks

# removeHooks

# attachVideoEvents

# detachVideoEvents

# setEventsMiddleware

# removeEventsMiddleware

API