video

基础库 1.0.0 开始支持本组件。

视频组件。相关 API 请参考 tt.createVideoContext。

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
src	string		是	要播放的视频资源地址	1.0.0
autoplay	boolean	false	否	是否自动播放	1.0.0
poster	string		否	视频封面的图片网络资源地址	1.0.0
loop	boolean	false	否	是否循环播放	1.47.0
show-fullscreen-btn	boolean	true	否	是否显示全屏按钮	1.47.0
show-play-btn	boolean	true	否	是否显示播放、暂停、重播按钮，不包括视频封面的播放按钮	1.47.0
controls	boolean	true	否	是否显示全部播放控件	1.47.0
object-fit	string	contain	否	当视频大小与 video 容器大小不一致时，视频的表现形式：contain（包含），fill（填充），cover（覆盖）	1.47.0
play-btn-position	string	center	否	播放按钮的位置：center（视频中间），bottom（控制条上）	1.47.0
pre-roll-unit-id	string		否	前贴广告的 unit id	1.62.0
post-roll-unit-id	string		否	后贴广告的 unit id	1.62.0
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量	2.3.0
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势，开启后表现详见手势响应-亮度与音量	2.3.0
enable-progress-gesture	boolean	false	否	是否开启控制进度的手势，开启后表现详见手势响应-播放进度	2.3.0
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停	2.3.0
muted	boolean	false	否	是否静音播放	2.4.0
show-mute-btn	boolean	false	否	是否显示静音控件	2.4.0
show-playback-rate-btn	boolean	false	否	是否显示倍速控件，点击倍速控件后可选择倍速，可选值： 0.75/1.0/1.25/1.5/2	2.5.0
direction	number	-90	否	设置全屏时视频的方向，详见 direction 的合法值	2.13.0
enable-play-in-background	boolean	false	否	video 播放时宿主退出后台后开启小窗播放，iOS 14 及以上版本支持。开启时首次退出后台后给予弹窗提示用户授权，授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放	2.16.0
signature	Signature		否	设置署名水印	2.48.0
bindplay	EventHandle		否	当开始播放时触发 play 事件	1.0.0
bindpause	EventHandle		否	当暂停播放时触发 pause 事件	1.0.0
bindended	EventHandle		否	当播放到末尾时触发 ended 事件	1.0.0
binderror	EventHandle		否	视频播放出错时触发 error 事件	1.0.0
bindtimeupdate	EventHandle		否	播放进度变化时触发，返回当前播放时间点及视频总时长，单位：秒(s)。`event.detail = { currentTime, duration }`	1.18.0
bindprogress	EventHandle		否	视频缓冲进度更新时触发，`event.detail = { buffered }`。其中 buffered 是百分比，取值是 [0, 100] 中的整数，如 buffered 为 50 表示当前视频缓冲了 50%。	2.65.0
bindfullscreenchange	EventHandle		否	视频进入和退出全屏时触发	1.18.0
bindwaiting	EventHandle		否	视频出现缓冲时触发	1.47.0
bindadstart	EventHandle		否	贴片广告开始播放时触发，`event.detail = { adType: 'preRollAd' \| 'postRollAd' }`	1.62.0
bindadended	EventHandle		否	贴片广告播放结束时触发，`event.detail = { adType: 'preRollAd' \| 'postRollAd' }`	1.62.0
bindadload	EventHandle		否	贴片广告加载成功时触发，`event.detail = { adType: 'preRollAd' \| 'postRollAd' }`	1.62.0
bindadclose	EventHandle		否	贴片广告非自然结束时触发，如：用户关闭广告或广告播放过程中 video 组件被销毁，`event.detail = { adType: 'preRollAd' \| 'postRollAd' }`	1.62.0
bindaderror	EventHandle		否	贴片广告加载失败时触发，`event.detail = { adType: 'preRollAd' \| 'postRollAd' }`	1.62.0
bindloadedmetadata	EventHandle		否	视频元数据加载完成时触发。`event.detail = {width, height, duration}`	1.90.0
bindseekcomplete	EventHandle		否	seek 完成时触发。返回 seek 完成后的播放时间点，单位：秒(s)。`event.detail={position}`	2.11.0
bindplaybackratechange	EventHandle		否	视频倍速改变完成时触发。返回改变后的倍速值。`event.detail={playbackRate}`	2.11.0
bindmutechange	EventHandle		否	静音状态改变完成时触发。返回当前是否静音。`event.detail={isMuted}`	2.11.0
bindcontroltap	EventHandle		否	点击控件时触发。返回当前点击的控件类型。`event.detail={controlType}`，取值见表 controlType 的合法值	2.11.0
bindenterbackground	EventHandle		否	进入小窗播放时触发	2.16.0
bindclosebackground	EventHandle		否	关闭小窗播放时触发	2.16.0
bindleavebackground	EventHandle		否	离开小窗进入 app 事件时触发	2.16.0

Signature 类型说明

object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
enable	boolean	true	否	是否显示署名水印	2.48.0
content	string		是	署名水印内容	2.48.0
position	number	0	否	署名水印位置：0（右上）， 1（右下）， 2（左下）， 3（左上）	2.48.0
color	Color	#FFFFFF	否	署名水印颜色，只支持 HEX 格式	2.48.0

object-fit 的合法值

值	说明	最低支持版本
contain	包含。内容将会在填充内容框的时候保持其宽高比例缩放，因此如果宽高比与内容框的宽高比不匹配，将会有黑边	1.47.0
fill	填充。如果内容的宽高比与内容框的不匹配，该对象将被拉伸以适应内容框	1.47.0
cover	覆盖。内容在保持其宽高比的同时填充整个内容框。如果内容的宽高比与内容框不匹配，该对象将被裁剪以适应内容框	1.47.0

play-btn-position 的合法值

值	说明	最低支持版本
center	视频中间	1.47.0
bottom	控制条上	1.47.0

direction 的合法值

值	说明	最低支持版本
0	正常竖向	2.13.0
90	屏幕逆时针 90 度	2.13.0
-90	屏幕顺时针 90 度	2.13.0

controlType 的合法值

值	说明	最低支持版本
play	播放控件 / 重播控件 (不包括点击视频初始状态的播放按钮)	2.11.0
pause	暂停控件	2.11.0
fullscreen	全屏控件	2.11.0
mute	静音控件	2.11.0
playbackRate	倍速控件（不包括倍速选择面板）	2.11.0
progress	进度控件，在刚开始拖动进度条时触发	2.11.0

手势响应

指定相应手势属性后，video 支持以下行为表现。

亮度与音量

开启亮度与音量手势后，以视频组件横向中心点为分界线，行为见下表：

滑动区域	表现	行为
左侧	调节亮度	上滑增大，下滑减小
右侧	调节音量	上滑增大，下滑减小

指示控件消失时机：松手 1s 无操作消失。

播放进度

开启进度手势后，左右滑动屏幕，调节播放进度（右滑增大、左滑减小）。指示控件消失时机：松手后时间提示立即消失。

后台小窗播放

关键特征	描述
小窗时机	宿主退出后台（支持移动小窗到任意位置）
退后台场景	跳转到其他 app、点击 home 键退到后台、打开最近任务列表
不包含场景	点击小程序关闭按钮
小窗优先级	多个 video 开启后台小窗播放时，后台小窗的 video 以播放次序优先，autoplay 情况播放次序不确定

支持格式

不同的 APP 宿主以及不同的系统对视频格式的支持程度是不一样的。

今日头条

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	√	X
flv	√	X
3gp	√	X
webm	√	X
hls	√	√

抖音

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	√	X
flv	√	X
3gp	√	X
webm	X	X
hls	√	√

西瓜视频

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	√	X
flv	√	X
3gp	√	X
webm	√	X
hls	√	√

皮皮虾

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	X	X
flv	X	X
3gp	X	X
webm	X	X
hls	√	√

火山小视频

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	X	X
flv	X	X
3gp	X	X
webm	X	X
hls	√	√

头条 Lite

视频格式	Android	iOS
mp4	√	√
m3u8	√	√
mov	√	√
m4v	√	√
avi	√	X
flv	√	X
3gp	√	X
webm	√	X
hls	√	√

贴片广告申请流程

申请流程：小程序开发者平台 --> 进入目标小程序 --> 广告中心 --> 流量主。目前仅支持企业用户。

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

Bug & Tip

Bug：给 video 或其父节点绑定 catch* 事件，可能会导致 video 播放控件不可用；
Tip：不同的 APP 宿主以及不同的系统对视频格式的支持程度是不一样，请参考文档中的详细说明；
Tip：贴片广告功能目前仅供企业用户使用，需要在小程序开发者平台申请；
Tip：避免在退出全屏操作过程中更新数据；
Tip：建议不要在一个页面中嵌入 3 个以上的 video 组件；
Tip：IDE 中 video 和真机上 web video 支持设置 border-radius，真机上其他类型的 video 暂不支持；
Tip：video 组件过小时不会显示控件（width < 250 || height < 140 时)；
Tip：更新 src 时，会对 src 做校验，需要保证设置的 src 以 ' '' 或 'file://' 开头，否则更新 src 会失败；
Tip：src和poster使用网络链接资源时，基于网络安全考虑，强烈建议使用https协议，对已有的http协议的链接也强烈建议升级到https。

点击纠错

该文档是否对你的开发有所帮助？

有帮助

没帮助

该文档是否对你的开发有所帮助？

有帮助

没帮助

video
属性说明
扫码体验
代码示例
Bug & Tip