# video
基礎(chǔ)庫(kù) 1.0.0 開(kāi)始支持，低版本需做兼容處理。
微信 Windows 版：支持
微信 Mac 版：支持
微信 鴻蒙 OS 版：支持
相關(guān)文檔: wx.createVideoContext
渲染框架支持情況：Skyline （使用最新 Nightly 工具調(diào)試）、WebView
# 功能描述
視頻（v2.4.0 起支持同層渲染）。
# 通用屬性
| 屬性 | 類型 | 默認(rèn)值 | 必填 | 說(shuō)明 | 最低版本 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| src | string | 是 | 要播放視頻的資源地址，支持網(wǎng)絡(luò)路徑、本地臨時(shí)路徑、云文件ID（2.3.0） | 1.0.0 | ||||||||||
| duration | number | 否 | 指定視頻時(shí)長(zhǎng) | 1.1.0 | ||||||||||
| controls | boolean | true | 否 | 是否顯示默認(rèn)播放控件（播放/暫停按鈕、播放進(jìn)度、時(shí)間） | 1.0.0 | |||||||||
| danmu-list | Array.<object> | 否 | 彈幕列表 | 1.0.0 | ||||||||||
| danmu-btn | boolean | false | 否 | 是否顯示彈幕按鈕，只在初始化時(shí)有效，不能動(dòng)態(tài)變更 | 1.0.0 | |||||||||
| enable-danmu | boolean | false | 否 | 是否展示彈幕，只在初始化時(shí)有效，不能動(dòng)態(tài)變更 | 1.0.0 | |||||||||
| autoplay | boolean | false | 否 | 是否自動(dòng)播放 | 1.0.0 | |||||||||
| loop | boolean | false | 否 | 是否循環(huán)播放 | 1.4.0 | |||||||||
| muted | boolean | false | 否 | 是否靜音播放 | 1.4.0 | |||||||||
| initial-time | number | 0 | 否 | 指定視頻初始播放位置 | 1.6.0 | |||||||||
| page-gesture | boolean | false | 否 | 在非全屏模式下，是否開(kāi)啟亮度與音量調(diào)節(jié)手勢(shì)（廢棄，見(jiàn) vslide-gesture） | 1.6.0 | |||||||||
| direction | number | 否 | 設(shè)置全屏?xí)r視頻的方向，不指定則根據(jù)寬高比自動(dòng)判斷 | 1.7.0 | ||||||||||
| ||||||||||||||
| show-progress | boolean | true | 否 | 若不設(shè)置，寬度大于240時(shí)才會(huì)顯示 | 1.9.0 | |||||||||
| show-fullscreen-btn | boolean | true | 否 | 是否顯示全屏按鈕 | 1.9.0 | |||||||||
| show-play-btn | boolean | true | 否 | 是否顯示視頻底部控制欄的播放按鈕 | 1.9.0 | |||||||||
| show-center-play-btn | boolean | true | 否 | 是否顯示視頻中間的播放按鈕 | 1.9.0 | |||||||||
| enable-progress-gesture | boolean | true | 否 | 是否開(kāi)啟控制進(jìn)度的手勢(shì) | 1.9.0 | |||||||||
| object-fit | string | contain | 否 | 當(dāng)視頻大小與 video 容器大小不一致時(shí)，視頻的表現(xiàn)形式 | 1.0.0 | |||||||||
| ||||||||||||||
| poster | string | 否 | 視頻封面的圖片網(wǎng)絡(luò)資源地址或云文件ID（2.3.0）。若 controls 屬性值為 false 則設(shè)置 poster 無(wú)效 | 1.0.0 | ||||||||||
| show-mute-btn | boolean | false | 否 | 是否顯示靜音按鈕 | 2.4.0 | |||||||||
| title | string | 否 | 視頻的標(biāo)題，全屏?xí)r在頂部展示 | 2.4.0 | ||||||||||
| play-btn-position | string | bottom | 否 | 播放按鈕的位置 | 2.4.0 | |||||||||
| ||||||||||||||
| enable-play-gesture | boolean | false | 否 | 是否開(kāi)啟播放手勢(shì)，即雙擊切換播放/暫停 | 2.4.0 | |||||||||
| auto-pause-if-navigate | boolean | true | 否 | 當(dāng)跳轉(zhuǎn)到本小程序的其他頁(yè)面時(shí)，是否自動(dòng)暫停本頁(yè)面的視頻播放 | 2.5.0 | |||||||||
| auto-pause-if-open-native | boolean | true | 否 | 當(dāng)跳轉(zhuǎn)到其它微信原生頁(yè)面時(shí)，是否自動(dòng)暫停本頁(yè)面的視頻 | 2.5.0 | |||||||||
| vslide-gesture | boolean | false | 否 | 在非全屏模式下，是否開(kāi)啟亮度與音量調(diào)節(jié)手勢(shì)（同 page-gesture） | 2.6.2 | |||||||||
| vslide-gesture-in-fullscreen | boolean | true | 否 | 在全屏模式下，是否開(kāi)啟亮度與音量調(diào)節(jié)手勢(shì) | 2.6.2 | |||||||||
| show-bottom-progress | boolean | true | 否 | 是否展示底部進(jìn)度條 | 2.8.0 | |||||||||
| ad-unit-id | string | 是 | 視頻前貼廣告單元ID，更多詳情可參考開(kāi)放能力視頻前貼廣告 | 2.8.1 | ||||||||||
| poster-for-crawler | string | 是 | 用于給搜索等場(chǎng)景作為視頻封面展示，建議使用無(wú)播放 icon 的視頻封面圖，只支持網(wǎng)絡(luò)地址 | |||||||||||
| show-casting-button | boolean | false | 否 | 顯示投屏按鈕。安卓在同層渲染下生效，支持 DLNA 協(xié)議；iOS 支持 AirPlay 和 DLNA 協(xié)議；鴻蒙 OS 暫不支持?？梢酝ㄟ^(guò)VideoContext的相關(guān)方法進(jìn)行操作。 | 2.10.2 | |||||||||
| picture-in-picture-mode | string/Array | 否 | 設(shè)置小窗模式： push, pop，空字符串或通過(guò)數(shù)組形式設(shè)置多種模式（如： ["push", "pop"]）。鴻蒙 OS 暫不支持 | 2.11.0 | ||||||||||
| ||||||||||||||
| picture-in-picture-show-progress | boolean | false | 否 | 是否在小窗模式下顯示播放進(jìn)度 | 2.11.0 | |||||||||
| picture-in-picture-init-position | string | 否 | 小窗模式下小窗的初始顯示位置，格式為 (alignment, y)，其中 alignment 表示小窗吸附屏幕左側(cè)還是右側(cè)，可選值為 left、right，y 代表小窗最頂部所在的屏幕高度百分比 | 3.3.0 | ||||||||||
| enable-auto-rotation | boolean | false | 否 | 是否開(kāi)啟手機(jī)橫屏?xí)r自動(dòng)全屏，當(dāng)系統(tǒng)設(shè)置開(kāi)啟自動(dòng)旋轉(zhuǎn)時(shí)生效 | 2.11.0 | |||||||||
| show-screen-lock-button | boolean | false | 否 | 是否顯示鎖屏按鈕，僅在全屏?xí)r顯示，鎖屏后控制欄的操作 | 2.11.0 | |||||||||
| show-snapshot-button | boolean | false | 否 | 是否顯示截屏按鈕，僅在全屏?xí)r顯示 | 2.13.0 | |||||||||
| show-background-playback-button | boolean | true | 否 | 是否展示后臺(tái)音頻播放按鈕。鴻蒙 OS 暫不支持。基礎(chǔ)庫(kù) 3.6.0 開(kāi)始默認(rèn)值為 true。 | 2.14.3 | |||||||||
| background-poster | string | 否 | 進(jìn)入后臺(tái)音頻播放后的通知欄圖標(biāo)（Android 獨(dú)有） | 2.14.3 | ||||||||||
| referrer-policy | string | no-referrer | 否 | 格式固定為 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 為小程序的 appid，{version} 為小程序的版本號(hào)，版本號(hào)為 0 表示為開(kāi)發(fā)版、體驗(yàn)版以及審核版本，版本號(hào)為 devtools 表示為開(kāi)發(fā)者工具，其余為正式版本； | 2.13.0 | |||||||||
| ||||||||||||||
| is-drm | boolean | 否 | 是否為 DRM 視頻源 | 2.19.3 | ||||||||||
| is-live | boolean | 否 | 是否為直播源 | 2.28.1 | ||||||||||
| provision-url | string | 否 | DRM 設(shè)備身份認(rèn)證 url，僅 is-drm 為 true 時(shí)生效 (Android) | 2.19.3 | ||||||||||
| certificate-url | string | 否 | DRM 設(shè)備身份認(rèn)證 url，僅 is-drm 為 true 時(shí)生效 (iOS) | 2.19.3 | ||||||||||
| license-url | string | 否 | DRM 獲取加密信息 url，僅 is-drm 為 true 時(shí)生效 | 2.19.3 | ||||||||||
| preferred-peak-bit-rate | number | 否 | 指定碼率上界，單位為比特每秒 | 2.26.0 | ||||||||||
| bindplay | eventhandle | 否 | 當(dāng)開(kāi)始/繼續(xù)播放時(shí)觸發(fā)play事件 | 1.0.0 | ||||||||||
| bindpause | eventhandle | 否 | 當(dāng)暫停播放時(shí)觸發(fā) pause 事件 | 1.0.0 | ||||||||||
| bindended | eventhandle | 否 | 當(dāng)播放到末尾時(shí)觸發(fā) ended 事件 | 1.0.0 | ||||||||||
| bindtimeupdate | eventhandle | 否 | 播放進(jìn)度變化時(shí)觸發(fā)，event.detail = {currentTime, duration} 。觸發(fā)頻率 250ms 一次 | 1.0.0 | ||||||||||
| bindfullscreenchange | eventhandle | 否 | 視頻進(jìn)入和退出全屏?xí)r觸發(fā)，event.detail = {fullScreen, direction}，direction 有效值為 vertical 或 horizontal | 1.4.0 | ||||||||||
| bindwaiting | eventhandle | 否 | 視頻出現(xiàn)緩沖時(shí)觸發(fā) | 1.7.0 | ||||||||||
| binderror | eventhandle | 否 | 視頻播放出錯(cuò)時(shí)觸發(fā) | 1.7.0 | ||||||||||
| bindprogress | eventhandle | 否 | 加載進(jìn)度變化時(shí)觸發(fā)，只支持一段加載。event.detail = {buffered}，百分比 | 2.4.0 | ||||||||||
| bindloadedmetadata | eventhandle | 否 | 視頻元數(shù)據(jù)加載完成時(shí)觸發(fā)。event.detail = {width, height, duration} | 2.7.0 | ||||||||||
| bindcontrolstoggle | eventhandle | 否 | 切換 controls 顯示隱藏時(shí)觸發(fā)。event.detail = {show} | 2.9.5 | ||||||||||
| bindenterpictureinpicture | eventhandler | 否 | 播放器進(jìn)入小窗 | 2.11.0 | ||||||||||
| bindleavepictureinpicture | eventhandler | 否 | 播放器退出小窗 | 2.11.0 | ||||||||||
| bindseekcomplete | eventhandler | 否 | seek 完成時(shí)觸發(fā) (position iOS 單位 s, Android 單位 ms) | 2.12.0 | ||||||||||
| bindcastinguserselect | eventhandler | 否 | 用戶選擇投屏設(shè)備時(shí)觸發(fā) detail = { state: "success"/"fail" }。鴻蒙 OS 暫不支持 | 2.32.0 | ||||||||||
| bindcastingstatechange | eventhandler | 否 | 投屏成功/失敗時(shí)觸發(fā) detail = { type, state: "success"/"fail" }。鴻蒙 OS 暫不支持 | 2.32.0 | ||||||||||
| bindcastinginterrupt | eventhandler | 否 | 投屏被中斷時(shí)觸發(fā)。鴻蒙 OS 暫不支持 | 2.32.0 | ||||||||||
# Bug & Tip
tip：`video 默認(rèn)寬度 300px、高度 225px，可通過(guò) wxss 設(shè)置寬高。tip：從 2.4.0 起 video 支持同層渲染，更多請(qǐng)參考原生組件使用限制tip: 若當(dāng)前組件所在的頁(yè)面或全局開(kāi)啟了enablePassiveEvent配置項(xiàng)，該內(nèi)置組件可能會(huì)出現(xiàn)非預(yù)期表現(xiàn)（詳情參考 enablePassiveEvent 文檔）
# 支持的格式
| 格式 | iOS | Android |
|---|---|---|
| mp4 | √ | √ |
| mov | √ | x |
| m4v | √ | x |
| 3gp | √ | √ |
| avi | √ | x |
| m3u8 | √ | √ |
| webm | x | √ |
# 支持的編碼格式
| 格式 | iOS | Android |
|---|---|---|
| H.264 | √ | √ |
| HEVC | √ | √ |
| MPEG-4 | √ | √ |
| VP9 | x | √ |
# 小窗特性說(shuō)明
video 小窗支持以下三種觸發(fā)模式（在組件上設(shè)置 picture-in-picture-mode 屬性）：
push 模式，即從當(dāng)前頁(yè)跳轉(zhuǎn)至下一頁(yè)時(shí)出現(xiàn)小窗（頁(yè)面棧push）
pop 模式，即離開(kāi)當(dāng)前頁(yè)面時(shí)觸發(fā)（頁(yè)面棧pop）
以上兩種路由行為均觸發(fā)小窗
此外，小窗還支持以下特性：
小窗容器尺寸會(huì)根據(jù)原組件尺寸自動(dòng)判斷
點(diǎn)擊小窗，用戶會(huì)被導(dǎo)航回小窗對(duì)應(yīng)的播放器頁(yè)面
小窗出現(xiàn)后，用戶可點(diǎn)擊小窗右上角的關(guān)閉按鈕或調(diào)用 context.exitPictureInPicture() 接口關(guān)閉小窗
當(dāng)播放器進(jìn)入小窗模式后，播放器所在頁(yè)面處于 hide 狀態(tài)(觸發(fā) onHide 生命周期)，該頁(yè)面不會(huì)被銷毀。當(dāng)小窗被關(guān)閉時(shí)，播放器所在頁(yè)面會(huì)被 unload (觸發(fā) onUnload 生命周期)。
# DRM 加密播放
- 小程序開(kāi)發(fā)者獲取到 DRM 加密的 視頻地址、身份認(rèn)證 url、license url
- 使用 video 標(biāo)簽將以上幾個(gè)參數(shù)填入
- 小程序確認(rèn)該 video 為 DRM 視頻源，進(jìn)行 DRM 設(shè)備身份認(rèn)證并且獲取播放許可證
- 設(shè)備身份認(rèn)證通過(guò)并獲取播放許可證之后，由 DRM 底層進(jìn)行解密播放
# Q&A
Q：為什么設(shè)備身份認(rèn)證 url 要區(qū)分 Android 和 iOS ？
A：由于 Android 和 iOS 是基于不同的 DRM 協(xié)議，Android：widevine；iOS：fairplay，所以身份認(rèn)證這塊有所不同，需要分別提供身份認(rèn)證 url。
Q：license url 的格式是什么樣的？
A：目前 license url 需要支持標(biāo)準(zhǔn) license 回包，即裸 license