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 | |
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
时)。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助