开发
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 播放时宿主退出后台后开启小窗播放。开启时首次退出后台后给予弹窗提示用户授权,授权完成后可以到小程序「设置」中重设。支持场景见后台小窗播放2.16.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

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

补充代码示例

【代码示例 1】:贴片广告示例

pre-roll-unit-id, post-roll-unit-id 使用示例

需要在小程序开发者平台中申请(见下方贴片广告申请流程),目前仅支持企业用户

<view>
  <video
    id="myVideoAd"
    src="https://sf1-cdn-tos.douyinstatic.com/obj/microapp/frontend/sdk/1534422848153.mp4"
    bindadstart="onAdStart"
    bindadended="onAdEnd"
    bindadload="onAdLoad"
    bindadclose="onAdClose"
    bindaderror="onAdError"
    pre-roll-unit-id="61d8rglj30t6ham8h6"
    post-roll-unit-id="otchj59is15fhm0ch4"
  ></video>
</view>
Page({
  data: {},
  onAdStart(e) {
    tt.showToast({
      title: "广告开始",
    });
    console.log("广告开始", e);
  },
  onAdEnd(e) {
    tt.showToast({
      title: "广告结束",
    });
    console.log("广告结束", e);
  },
  onAdLoad(e) {
    tt.showToast({
      title: "广告加载成功",
    });
    console.log("广告加载成功", e);
  },
  onAdError(e) {
    tt.showToast({
      title: "广告加载失败",
    });
    console.log("广告加载失败", e);
  },
  onAdClose(e) {
    tt.showToast({
      title: "广告关闭",
    });
    console.log("广告关闭", e);
  },
});

贴片广告申请流程

申请流程:小程序开发者平台 --> 进入目标小程序 --> 广告中心 --> 流量主。

扫码体验

请使用字节宿主APP扫码

Bug & Tip

  • Tip:不同的 APP 宿主以及不同的系统对视频格式的支持程度是不一样,请参考文档中的详细说明。
  • Tip:贴片广告功能目前仅供企业用户使用,需要在小程序开发者平台申请。
  • Tip:避免在退出全屏操作过程中更新数据。
  • Tip:video 组件过小时不会显示控件(width < 250 || height < 140 时)。
点击纠错
评价此篇文档