开发
API
自2022年9月6日起,本文档站不再更新内容,相关文档已迁移至全新“抖音开放平台”前往

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