开发
API

video

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

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

属性说明

属性名类型默认值必填说明最低支持版本
srcstring要播放的视频资源地址1.0.0
autoplaybooleanfalse是否自动播放1.0.0
posterstring视频封面的图片网络资源地址1.0.0
loopbooleanfalse是否循环播放1.47.0
show-fullscreen-btnbooleantrue是否显示全屏按钮1.47.0
show-play-btnbooleantrue是否显示播放、暂停、重播按钮,不包括视频封面的播放按钮1.47.0
controlsbooleantrue是否显示全部播放控件1.47.0
object-fitstringcontain当视频大小与 video 容器大小不一致时,视频的表现形式:contain(包含),fill(填充),cover(覆盖)1.47.0
play-btn-positionstringcenter播放按钮的位置:center(视频中间),bottom(控制条上)1.47.0
pre-roll-unit-idstring前贴广告的 unit id1.62.0
post-roll-unit-idstring后贴广告的 unit id1.62.0
vslide-gesturebooleanfalse在非全屏模式下,是否开启亮度与音量调节手势,开启后表现详见手势响应-亮度与音量2.3.0
vslide-gesture-in-fullscreenbooleantrue在全屏模式下,是否开启亮度与音量调节手势,开启后表现详见手势响应-亮度与音量2.3.0
enable-progress-gesturebooleanfalse是否开启控制进度的手势,开启后表现详见手势响应-播放进度2.3.0
enable-play-gesturebooleanfalse是否开启播放手势,即双击切换播放/暂停2.3.0
mutedbooleanfalse是否静音播放2.4.0
show-mute-btnbooleanfalse是否显示静音控件2.4.0
show-playback-rate-btnbooleanfalse是否显示倍速控件,点击倍速控件后可选择倍速,可选值: 0.75/1.0/1.25/1.5/22.5.0
directionnumber-90设置全屏时视频的方向,详见 direction 的合法值2.13.0
enable-play-in-backgroundbooleanfalsevideo 播放时宿主退出后台后开启小窗播放,iOS 14 及以上版本支持。开启时首次退出后台后给予弹窗提示用户授权,授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放2.16.0
signatureSignature设置署名水印2.48.0
bindplayEventHandle当开始播放时触发 play 事件1.0.0
bindpauseEventHandle当暂停播放时触发 pause 事件1.0.0
bindendedEventHandle当播放到末尾时触发 ended 事件1.0.0
binderrorEventHandle视频播放出错时触发 error 事件1.0.0
bindtimeupdateEventHandle播放进度变化时触发,返回当前播放时间点及视频总时长,单位:秒(s)。event.detail = { currentTime, duration }1.18.0
bindfullscreenchangeEventHandle视频进入和退出全屏时触发1.18.0
bindwaitingEventHandle视频出现缓冲时触发1.47.0
bindadstartEventHandle贴片广告开始播放时触发,event.detail = { adType: 'preRollAd' | 'postRollAd' }1.62.0
bindadendedEventHandle贴片广告播放结束时触发,event.detail = { adType: 'preRollAd' | 'postRollAd' }1.62.0
bindadloadEventHandle贴片广告加载成功时触发,event.detail = { adType: 'preRollAd' | 'postRollAd' }1.62.0
bindadcloseEventHandle贴片广告非自然结束时触发,如:用户关闭广告或广告播放过程中 video 组件被销毁,event.detail = { adType: 'preRollAd' | 'postRollAd' }1.62.0
bindaderrorEventHandle贴片广告加载失败时触发,event.detail = { adType: 'preRollAd' | 'postRollAd' }1.62.0
bindloadedmetadataEventHandle视频元数据加载完成时触发。event.detail = {width, height, duration}1.90.0
bindseekcompleteEventHandleseek 完成时触发。返回 seek 完成后的播放时间点,单位:秒(s)。event.detail={position}2.11.0
bindplaybackratechangeEventHandle视频倍速改变完成时触发。返回改变后的倍速值。event.detail={playbackRate}2.11.0
bindmutechangeEventHandle静音状态改变完成时触发。返回当前是否静音。event.detail={isMuted}2.11.0
bindcontroltapEventHandle点击控件时触发。返回当前点击的控件类型。event.detail={controlType},取值见表 controlType 的合法值2.11.0
bindenterbackgroundEventHandle进入小窗播放时触发2.16.0
bindclosebackgroundEventHandle关闭小窗播放时触发2.16.0
bindleavebackgroundEventHandle离开小窗进入 app 事件时触发2.16.0

Signature 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
enablebooleantrue是否显示署名水印2.48.0
contentstring署名水印内容2.48.0
positionnumber0署名水印位置:0(右上), 1(右下), 2(左下), 3(左上)2.48.0
colorColor#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 宿主以及不同的系统对视频格式的支持程度是不一样的。

今日头条

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviX
flvX
3gpX
webmX
hls

抖音

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviX
flvX
3gpX
webmXX
hls

西瓜视频

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviX
flvX
3gpX
webmX
hls

皮皮虾

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviXX
flvXX
3gpXX
webmXX
hls

火山小视频

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviXX
flvXX
3gpXX
webmXX
hls

头条 Lite

视频格式AndroidiOS
mp4
m3u8
mov
m4v
aviX
flvX
3gpX
webmX
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 时)。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助