# video

更新时间：2024-12-09 11:57:47

基础库1.2.0开始支持,低版本需做兼容处理

开发者工具1.22.0开始支持

视频。相关 api：ks.createVideoContext (opens new window)

# 属性

属性	类型	默认值	必填	说明	最低版本
src	string		是	要播放视频的资源地址，支持网络路径、本地临时路径	-
controls	boolean	true	否	控制所有的控件展示与隐藏(除了全屏的返回按钮)。	-
autoplay	boolean	false	否	是否自动播放	-
loop	boolean	false	否	是否循环播放	-
muted	boolean	false	否	是否静音播放	-
initial-time	number	0	否	指定视频初始播放位置	-
page-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（废弃，见 vslide-gesture）	-
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（同 page-gesture）	1.63.0
direction	0 \| 90 \| -90		否	设置全屏时视频的方向	-
show-progress	boolean	true	否	控制进度条（包含左右两端的时间文字）的隐藏与展示，小屏和横竖屏全屏均生效。	-
show-bottom-controls	boolean	true	否	控制整个控制条区域（包括播放/暂停、进度条、全屏按钮、静音按钮、倍速按钮等）的显示与隐藏 (仅在全屏下生效)。	-
show-fullscreen-btn	boolean	true	否	是否显示全屏按钮，仅在小屏状态下显示，全屏状态下通过标题旁边的箭头退出全屏	-
show-play-btn	boolean	true	否	是否显示视频底部控制栏的播放按钮，仅在全屏时显示	-
enable-progress-gesture	boolean	true	否	是否开启控制进度的手势	-
object-fit	'contain' \| 'fill' \| 'cover'	'contain'	否	当视频大小与 video 容器大小不一致时，视频的表现形式	-
poster	string		否	视频封面的图片网络资源地址，若 controls 属性值为 false 则设置 poster 无效	-
show-mute-btn	boolean	false	否	是否显示静音按钮，仅在全屏时显示	-
title	string		否	视频的标题，全屏时在顶部展示	-
play-btn-position	'center' \| 'bottom'	'bottom'	否	播放按钮的位置(仅Android支持)	-
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停	-
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势	-
show-screen-lock-button	boolean	false	否	是否显示锁屏按钮，仅在全屏时显示	-
show-playback-rate-btn	boolean	false	否	是否显示倍速控件。点击倍速控件后可选择倍速，可选值： 0.5/0.75/1.0/1.25/1.5/2	-
show-bottom-progress	boolean	true	否	控制小屏场景下所有控件消失后展示的红色进度条的显示与隐藏。	-
enable-long-press-forward	boolean	true	否	是否允许长按倍速功能。	-
show-center-play-btn	boolean	true	否	是否显示视频中间的播放按钮。	-
show-casting-button	boolean	false	否	显示投屏按钮。安卓在同层渲染下生效，支持 DLNA 协议。可以通过VideoContext的相关方法进行操作。	1.94.0
referrer-policy	'origin' \| 'no-referrer'	'no-referrer'	否	格式固定为 `https://miniapi.ksapisrv.com/{appid}/{version}/page-frame.html`，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本；	-
bindplay	(e: { detail: Record<string, unknown> } & Event) => void		否	当开始/继续播放时触发 play 事件	-
bindpause	(e: { detail: Record<string, unknown> } & Event) => void		否	当暂停播放时触发 pause 事件	-
bindended	(e: { detail: Record<string, unknown> } & Event) => void		否	当播放到末尾时触发 ended 事件	-
bindtimeupdate	(e: { detail: Record<string, unknown> } & Event) => void		否	播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次	-
bindfullscreenchange	(e: { detail: Record<string, unknown> } & Event) => void		否	视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction 有效值为 vertical 或 horizontal	-
binderror	(e: { detail: Record<string, unknown> } & Event) => void		否	视频播放出错时触发	-
bindrendererror	(e: { detail: { videoPlayerId: string, errorCode: number, errMsg: string } } & Event) => void		否	同层失败时触发	1.40.0
bindcastinguserselect	(e: { detail: Record<string, unknown> } & Event) => void		否	用户选择投屏设备时触发 detail = { state: "success"/"fail" }	1.94.0
bindcastingstatechange	(e: { detail: Record<string, unknown> } & Event) => void		否	投屏成功/失败时触发 detail = { state: "success"/"fail" }	1.94.0
bindcastinginterrupt	(e: { detail: Record<string, unknown> } & Event) => void		否	投屏被中断时触发	1.94.0

# direction

设置全屏时视频的方向

值	说明
0	正常竖向
90	屏幕逆时针90度
-90	屏幕顺时针90度

# objectFit

当视频大小与 video 容器大小不一致时，视频的表现形式

值	说明
'contain'	包含
'fill'	填充
'cover'	覆盖

# playBtnPosition

播放按钮的位置(仅Android支持)

值	说明
'center'	视频中间
'bottom'	controls bar 上

# referrerPolicy

格式固定为 https://miniapi.ksapisrv.com/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本；

值	说明
'origin'	发送完整的referrer
'no-referrer'	不发送

# 支持的格式

格式	iOS	Android
mp4	√	√
m3u8	√	√
flv	√	√
mov	√	√
m4a	√	√
3gp	x	√
mp3	√	√

# 支持的编码格式

格式	iOS	Android
H.264	√	√
HEVC	√	√

# Bug & Tip

tip：video默认宽度为 100%、高度为 300px，可通过 css 设置宽高
tip：请注意原生组件使用限制 (opens new window)