API

播放组件提供原生js方式接入，React组件方式接入，Vue2/Vue3组件方式接入。原生js、React、Vue的API和事件名称有差异，需要注意。

播放器的属性、API及事件参考了HTMLVideoElement的实现。

需要参考的文档：

1. HTMLVideoElement
2. HTMLMediaElement

原生js组件属性

以下属性同HTMLVideoElement

属性	定义	备注
crossOrigin	跨域设置
preload	当前视频预加载设置
defaultPlaybackRate	默认播放速度
playbackRate	播放速度
autoplay	自动播放
loop	循环播放开关
controls	播放控件显示开关
volume	音量
muted	静音
defaultMuted	默认静音
poster	封面图
disablePictureInPicture	画中画是否可用开关
playsinline	手机H5小窗播放开关
buffered	缓存范围	只读
duration	视频时长	只读
ended	是否播放结束	只读
error	错误信息	只读
played	已播放范围	只读
readyState	视频状态	只读
seekable	可seek范围	只读
seeking	是否处于seek状态中	只读
networkState	当前视频加载网络状态	只读
paused	是否暂停状态	只读
videoWidth	视频源宽	只读
videoHeight	视频源高	只读

暂未实现的属性

• audioTracks
• currentSrc 只读
• initialTime 只读
• mediaGroup
• mediaKeys
• moz*
• sinkId
• textTracks
• videoTracks
• width
• height

width/height暂不支持，需要使用样式控制

与HTMLVideoElement有差异的属性

src

可传入视频URL、manifest JSON、File。可传入空字符串进入停止状态

controls

定义同HTMLVideoElement，用于控制播放控件，可选值有不同

• controls可选值说明
  • false：关闭播放控件，如果需要自定义播放控件请使用该选项
  • true：使用默认播放控件
  • 'default'：使用默认播放控件

disableDownload

controls===‘origin’时是否使下载功能可用

disableAdaptive

自适应码率是否可用，默认：true

以上已实现的可写属性均可在构造函数中传入

currentLevel

get: 返回当前正在加载的流index

set: 立即切换至指定的流index

设置为-1，切换至自动码率

nextLevel

get: 返回下一个加载的流index

set: 下一个切换的视频流index

设置为-1，切换至自动码率

audioTrack

get: 返回当前的音频轨index

set: 立即切换至指定的音频轨index

totalVideoFrames

get: 返回当前播视频总帧数

currentVideoFrame

get: 返回当前播放位置对应的帧index

set: seek至指定帧

showProgress

get: 设置是否显示进度条

set: 获取当前是否显示进度条

totalVideoFrames>0时可用

API

以下API同HTMLVideoElement

• load()
• play()
• pause()
• requestPictureInPicture();

以下API暂未实现

• ms*
• canPlayType()
• captureStream()
• fastSeek()
• setMediaKeys()
• setSinkId()

与HTMLVideoElement有差异的API

constructor(id: string, data?: Partial<KwaiPlayer.KwaiPlayerData>)

构造函数

参数说明：

• id: 播放器容器id
• data: 播放器参数，与HTMLVideoElement相同的API定义也可同data传入

type KwaiPlayerData = {
    src: any;
    crossOrigin?: string;
    preload?: string;
    defaultPlaybackRate?: number;
    playbackRate?: number;
    autoplay?: boolean;
    loop?: boolean;
    controls?: boolean | string;
    volume?: number;
    muted?: boolean;
    defaultMuted?: boolean;
    poster?: string;
    disablePictureInPicture?: boolean;
    disableDownload?: boolean;
    disableAdaptive?: boolean;
    playsinline?: boolean;
    plugins: { [key in string]: object }; // 参见插件说明
};

destroy(): void

销毁

isFullscreen(): boolean;

是否全屏

requestFullscreen: (type?: "window" | "system" | undefined) => void;

请求全屏
type?: "window" | "system" 窗口全屏 | 系统全屏

exitFullscreen: (type?: "window" | "system" | undefined) => void;

退出全屏
type?: "window" | "system" | undefined 窗口全屏 | 系统全屏 | 自动

requestPictureInPicture(): Promise | undefined;

进入画中画

原生js组件事件

以下事件同HTMLVideoElement

属性	定义	备注
abort	资源未完全加载时触发，非错误
canplay	可播时
canplaythrough	可播时，估计已加载足够数据
durationchange	视频总时长变更
emptied	媒体源设置为空时
ended	播放结束
error	发生错误
loadeddata	当前播放位置视频帧加载完成
loadedmetadata	metadata加载完成
loadstart	开始加载
pause	进入暂停状态 puased转为true时
play	进入播放状态 puased转为false时
playing	播放准备开始时
progress	加载资源
ratechange	播放速度变更
resize	视频源尺寸变更
seeked	seek完成
seeking	seek开始
stalled	尝试获取数据但是为取到时触发
suspend	加载数据被挂起
timeupdate	播放时间变更
volumechange	音量变更
waiting	缺少数据导致播放暂停

与HTMLVideoElement有差异的事件

以下事件与多清晰度相关

manifestparsed

• 定义：manifest解析成功事件
• 数据：

{
    levels: {
        width: 640, // 宽，可选
        height: 360, // 高，可选
        qualityType: "360"
        qualityLabel: "标清"
    }[], // 可用流列表
    currentLevel: 3, // 当前流index,
    audioTracks?: {
        lang: 'en', // 语言
        qualityLabel: '',
        qualityType: '',
    }[], // 可用音频轨
    audioTrack?: 0, // 当前音频轨index
}

levelswitching

• 定义：开始进行码率切换
• 数据：

  { 
	  bitrate: 460560, // 码率
	  smooth: true, // 是否平滑切换
      auto: false, // 是否自动
      level: 1, // level下标
      id: 1, // 切换操作id
  }

levelswitched

• 定义：码率切换成功事件
• 数据：

{ 
	bitrate: 460560, // 码率
	smooth: true, // 是否平滑切换
    auto: false, // 是否自动
    level: 1， // level下标
    id: 1, // 切换操作id
}

levelswitchplaying

• 定义：码率切换开始播放，切换至自动码率时无此事件
• 数据：

{ 
	bitrate: 460560, // 码率
	smooth: true, // 是否平滑切换
    auto: false, // 是否自动
    level: 1， // level下标
    id: 1, // 切换操作id
}

levelswitchfailed

• 定义：切换清晰度失败

audiotrackswitching

• 定义：音频轨开始切换
• 数据：

{
    level: 0,   // 音频轨id
    smooth: false,  // 是否平滑切换
    auto: false,    // 是否自动切换
    id: 1           // 切换操作id
}

audiotrackswitched

• 定义：音频轨切换完成
• 数据：

{
    level: 0,   // 音频轨id
    smooth: false,  // 是否平滑切换
    auto: false,    // 是否自动切换
    id: 1           // 切换操作id
}

React组件与原生js组件差异

API相同

React事件对应表

React组件事件	对应事件
onAbout	abort
onCanplay	canplay
onCanplayThrough	canplaythrough
onDurationChange	durationchange
onEmptied	emptied
onEnded	ended
onError	error
onLoadedData	loadeddata
onLoadedMetadata	loadedmetadata
onLoadStart	loadstart
onPause	pause
onPlay	play
onPlaying	playing
onProgress	progress
onRateChange	ratechange
onResize	resize
onSeeked	seeked
onSeeking	seeking
onStalled	stalled
onSuspend	suspend
onTimeUpdate	timeupdate
onVolumeChange	volumechange
onWaiting	waiting
onManifestParsed	manifestparsed
onLevelSwitching	levelswitching
onLevelSwitched	levelswitched
onLevelSwitchPlaying	levelswitchplaying
onLevelSwitchFailed	levelswitchfailed
onAudioTrackSwitching	audiotrackswitching
onAudioTrackSwitched	audiotrackswitched

Vue组件与原生js组件差异

事件相同

以下props同HTMLVideoElement

• crossOrigin //是否设置跨域
• preload //是否预加载
• defaultPlaybackRate //设置默认播放倍速
• playbackRate //修改播放倍速
• autoplay //是否设置视频播自动播放
• loop //是否在视频播放结束的时候，自动返回视频开始的地方，继续播放
• controls //是否在视频底部使用默认面板 包括控制音量，跨帧，暂停/播放等
• volume //设置音量
• muted //设置音量是否静音
• defaultMuted //设置音量是否默认静音
• poster //视频播放之前，作为海报展示的图片
• disablePictureInPicture //是否禁用画中画选项
• playsinline //指明视频将内联（inline）播放，即在元素的播放区域内
• src //播放URL或者manifest内容

Vue组件属性对照表

Vue组件 API	原生js组件属性
getError	error
getNetworkState	networkState
getBuffered	buffered
getReadyState	readyState
getSeeking	seeking
getDuration	duration
getPaused	paused
getSeekable	seekable
getEnded	ended
getVideoWidth	videoWidth
getVideoHeight	videoHeight
getSrc / setSrc	src
getCrossOrigin / setCrossOrigin	crossOrigin
getPreload / setPreload	preload
getCurrentTime / setCurrentTime	currentTime
getDefaultPlaybackRate / setDefaultPlaybackRate	defaultPlaybackRate
getPlaybackRate / setPlaybackRate	playbackRate
getAutoplay / setAutoplay	autoplay
getLoop / setLoop	loop
getControls / setControls	controls
getVolume / setVolume	volume
getMuted / setMuted	muted
getDefaultMuted / setDefaultMuted	defaultMuted
getPoster / setPoster	poster
getDisablePictureInPicture / setDisablePictureInPicture	disablePictureInPicture
getPlaysinline / setPlaysinline	playsinline + webkit-playsinline + x5-playsinline