媒体组件
优质
小牛编辑
135浏览
2023-12-01
媒体组件说明
| 组件 | 说明 | 最低版本 | 备注 |
|---|---|---|---|
| audio | 音频 | 1.0.0 | |
| image | 图片 | 1.0.0 | |
| video | 视频 | 1.0.0 | |
| camera | 照相机 | 2.9.3 | |
| live-player | 实时音频播放 | 2.10.1 | 需配合第三方音视频 SDK 使用 |
| live-pusher | 实时音频录制 | 2.10.1 | 需配合第三方音视频 SDK 使用 |
| voip-room | 多人音视频对话 | 不支持 |
audio
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| id | string | 否 | audio 组件的唯一标识符 | 1.0.0 | |
| src | string | 否 | 要播放音频的资源地址 | 1.0.0 | |
| loop | boolean | false | 否 | 是否循环播放 | 1.0.0 |
| controls | boolean | false | 否 | 是否显示默认控件 | 1.0.0 |
| poster | string | 否 | 默认控件上的音频封面的图片资源地址，如果 controls 属性值为 false 则设置 poster 无效 | 1.0.0 | |
| name | string | 未知音频 | 否 | 默认控件上的音频名字，如果 controls 属性值为 false 则设置 name 无效 | 1.0.0 |
| author | string | 未知作者 | 否 | 默认控件上的作者名字，如果 controls 属性值为 false 则设置 author 无效 | 1.0.0 |
| binderror | eventhandle | 否 | 当发生错误时触发 error 事件，detail = {errMsg:MediaError.code} | 1.0.0 | |
| bindplay | eventhandle | 否 | 当开始/继续播放时触发play事件 | 1.0.0 | |
| bindpause | eventhandle | 否 | 当暂停播放时触发 pause 事件 | 1.0.0 | |
| bindtimeupdate | eventhandle | 否 | 当播放进度改变时触发 timeupdate 事件，detail = {currentTime, duration} | 1.0.0 | |
| bindended | eventhandle | 否 | 当播放到末尾时触发 ended 事件 | 1.0.0 |
image
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| src | string | 否 | 图片资源地址 | ||
| mode | string | scaleToFill | 否 | 图片裁剪、缩放的模式 | |
| binderror | eventhandle | 否 | 当错误发生时触发，event.detail = {errMsg} | ||
| bindload | eventhandle | 否 | 当图片载入完毕时触发，event.detail = {height, width} | ||
| webp | boolean | false | 否 | 默认不解析 webP 格式，只支持网络资源 | 不支持 |
| lazy-load | boolean | false | 否 | 图片懒加载，在即将进入一定范围（上下三屏）时才开始加载 | 不支持 |
| show-menu-by-longpress | boolean | false | 否 | 开启长按图片显示识别小程序码菜单 | 不支持 |
mode 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| scaleToFill | 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素 | |
| aspectFit | 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。 | |
| aspectFill | 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 | |
| widthFix | 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变 | |
| heightFix | 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 | |
| top | 裁剪模式，不缩放图片，只显示图片的顶部区域 | |
| bottom | 裁剪模式，不缩放图片，只显示图片的底部区域 | |
| center | 裁剪模式，不缩放图片，只显示图片的中间区域 | |
| left | 裁剪模式，不缩放图片，只显示图片的左边区域 | |
| right | 裁剪模式，不缩放图片，只显示图片的右边区域 | |
| top left | 裁剪模式，不缩放图片，只显示图片的左上边区域 | |
| top right | 裁剪模式，不缩放图片，只显示图片的右上边区域 | |
| bottom left | 裁剪模式，不缩放图片，只显示图片的左下边区域 | |
| bottom right | 裁剪模式，不缩放图片，只显示图片的右下边区域 |
live-player
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| src | string | 否 | 音视频地址。目前仅支持 flv, rtmp 格式 | 1.7.0 | |
| mode | string | live | 否 | 模式 | 1.7.0 |
| autoplay | boolean | false | 否 | 自动播放 | 1.7.0 |
| muted | boolean | false | 否 | 是否静音 | 1.7.0 |
| orientation | string | vertical | 否 | 画面方向 | 1.7.0 |
| object-fit | string | contain | 否 | 填充模式，可选值有 contain，fillCrop | 1.7.0 |
| background-mute | boolean | false | 否 | 进入后台时是否静音（已废弃，默认退后台静音） | 1.7.0 |
| min-cache | number | 1 | 否 | 最小缓冲区，单位s（RTC 模式推荐 0.2s） | 1.7.0 |
| max-cache | number | 3 | 否 | 最大缓冲区，单位s（RTC 模式推荐 0.8s）。缓冲区用来抵抗网络波动，缓冲数据越多，网络抗性越好，但时延越大。 | 1.7.0 |
| sound-mode | string | speaker | 否 | 声音输出方式 | 1.9.90 |
| auto-pause-if-navigate | boolean | true | 否 | 当跳转到本小程序的其他页面时，是否自动暂停本页面的实时音视频播放 | 2.5.0 |
| auto-pause-if-open-native | boolean | true | 否 | 当跳转到其它微信原生页面时，是否自动暂停本页面的实时音视频播放 | 2.5.0 |
| picture-in-picture-mode | string/Array | 否 | 设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： ["push", "pop"]） | 2.10.3 | |
| bindstatechange | eventhandle | 否 | 播放状态变化事件，detail = {code} | 1.7.0 | |
| bindfullscreenchange | eventhandle | 否 | 全屏变化事件，detail = {direction, fullScreen} | 1.7.0 | |
| bindnetstatus | eventhandle | 否 | 网络状态通知，detail = {info} | 1.9.0 | |
| bindaudiovolumenotify | eventhandler | 否 | 播放音量大小通知，detail = {} | 2.10.0 | |
| bindenterpictureinpicture | eventhandler | 否 | 播放器进入小窗 | 2.11.0 | |
| bindleavepictureinpicture | eventhandler | 否 | 播放器退出小窗 | 2.11.0 |
mode 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| live | 直播 | |
| RTC | 实时通话，该模式时延更低 |
orientation 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| vertical | 竖直 | |
| horizontal | 水平 |
object-fit 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| contain | 图像长边填满屏幕，短边区域会被填充⿊⾊ | |
| fillCrop | 图像铺满屏幕，超出显示区域的部分将被截掉 |
sound-mode 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| speaker | 扬声器 | |
| ear | 听筒 |
picture-in-picture-mode 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| [] | 取消小窗 | |
| push | 路由 push 时触发小窗 | |
| pop | 路由 pop 时触发小窗 |
状态码
| 代码 | 说明 |
|---|---|
| 2001 | 已经连接服务器 |
| 2002 | 已经连接 RTMP 服务器,开始拉流 |
| 2003 | 网络接收到首个视频数据包(IDR) |
| 2004 | 视频播放开始 |
| 2005 | 视频播放进度 |
| 2006 | 视频播放结束 |
| 2007 | 视频播放Loading |
| 2008 | 解码器启动 |
| 2009 | 视频分辨率改变 |
| -2301 | 网络断连，且经多次重连抢救无效，更多重试请自行重启播放 |
| -2302 | 获取加速拉流地址失败 |
| 2101 | 当前视频帧解码失败 |
| 2102 | 当前音频帧解码失败 |
| 2103 | 网络断连, 已启动自动重连 |
| 2104 | 网络来包不稳：可能是下行带宽不足，或由于主播端出流不均匀 |
| 2105 | 当前视频播放出现卡顿 |
| 2106 | 硬解启动失败，采用软解 |
| 2107 | 当前视频帧不连续，可能丢帧 |
| 2108 | 当前流硬解第一个I帧失败，SDK自动切软解 |
| 3001 | RTMP -DNS解析失败 |
| 3002 | RTMP服务器连接失败 |
| 3003 | RTMP服务器握手失败 |
| 3005 | RTMP 读/写失败，之后会发起网络重试 |
网络状态数据
| 键名 | 说明 |
|---|---|
| videoBitrate | 当前视频编/码器输出的比特率，单位 kbps |
| audioBitrate | 当前音频编/码器输出的比特率，单位 kbps |
| videoFPS | 当前视频帧率 |
| videoGOP | 当前视频 GOP,也就是每两个关键帧(I帧)间隔时长，单位 s |
| netSpeed | 当前的发送/接收速度 |
| netJitter | 网络抖动情况，为 0 时表示没有任何抖动，值越大表明网络抖动越大，网络越不稳定 |
| netQualityLevel | 网络质量：0：未定义 1：最好 2：好 3：一般 4：差 5：很差 6：不可用 |
| videoWidth | 视频画面的宽度 |
| videoHeight | 视频画面的高度 |
| videoCache | 缓冲的视频总时长，单位毫秒 |
| audioCache | 缓冲的音频总时长，单位毫秒 |
| vDecCacheSize | 解码器中缓存的视频帧数 (Android 端硬解码时存在） |
| vSumCacheSize | 缓冲的总视频帧数，该数值越大，播放延迟越高 |
| avPlayInterval | 音画同步错位时间（播放），单位 ms，此数值越小，音画同步越好 |
| avRecvInterval | 音画同步错位时间（网络），单位 ms，此数值越小，音画同步越好 |
| audioCacheThreshold | 音频缓冲时长阈值，缓冲超过该阈值后，播放器会开始调控延时 |
live-pusher
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| url | string | 否 | 推流地址。目前仅支持 rtmp 格式 | 1.7.0 | |
| mode | string | RTC | 否 | SD（标清）, HD（高清）, FHD（超清）, RTC（实时通话） | 1.7.0 |
| autopush | boolean | false | 否 | 自动推流 | 1.7.0 |
| muted | boolean | false | 否 | 是否静音。即将废弃，可用 enable-mic 替代 | 1.7.0 |
| enable-camera | boolean | true | 否 | 开启摄像头 | 1.7.0 |
| auto-focus | boolean | true | 否 | 自动聚集 | 1.7.0 |
| orientation | string | vertical | 否 | 画面方向 | 1.7.0 |
| beauty | number | 0 | 否 | 美颜，取值范围 0-9 ，0 表示关闭 | 1.7.0 |
| whiteness | number | 0 | 否 | 美白，取值范围 0-9 ，0 表示关闭 | 1.7.0 |
| aspect | string | 9:16 | 否 | 宽高比，可选值有 3:4, 9:16 | 1.7.0 |
| min-bitrate | number | 200 | 否 | 最小码率 | 1.7.0 |
| max-bitrate | number | 1000 | 否 | 最大码率 | 1.7.0 |
| audio-quality | string | high | 否 | 高音质(48KHz)或低音质(16KHz)，值为high, low | 1.7.0 |
| waiting-image | string | 否 | 进入后台时推流的等待画面 | 1.7.0 | |
| waiting-image-hash | string | 否 | 等待画面资源的MD5值 | 1.7.0 | |
| zoom | boolean | false | 否 | 调整焦距 | 2.1.0 |
| device-position | string | front | 否 | 前置或后置，值为front, back | 2.3.0 |
| background-mute | boolean | false | 否 | 进入后台时是否静音（已废弃，默认退后台静音） | 1.7.0 |
| mirror | boolean | false | 否 | 设置推流画面是否镜像，产生的效果在 live-player 反应到 | 2.7.0 |
| remote-mirror | boolean | false | 否 | 同 mirror 属性，后续 mirror 将废弃 | 2.10.0 |
| local-mirror | string | auto | 否 | 控制本地预览画面是否镜像 | 2.10.0 |
| audio-reverb-type | number | 0 | 否 | 音频混响类型 | 2.10.0 |
| enable-mic | boolean | true | 否 | 开启或关闭麦克风 | 2.10.0 |
| enable-agc | boolean | false | 否 | 是否开启音频自动增益 | 2.10.0 |
| enable-ans | boolean | false | 否 | 是否开启音频噪声抑制 | 2.10.0 |
| audio-volume-type | string | auto | 否 | 音量类型 | 2.10.0 |
| video-width | number | 360 | 否 | 上推的视频流的分辨率宽度 | 2.10.0 |
| video-height | number | 640 | 否 | 上推的视频流的分辨率高度 | 2.10.0 |
| beauty-style | string | smooth | 否 | 设置美颜类型 | 2.12.0 |
| filter | string | standard | 否 | 设置色彩滤镜 | 2.12.0 |
| bindstatechange | eventhandle | 否 | 状态变化事件，detail = {code} | 1.7.0 | |
| bindnetstatus | eventhandle | 否 | 网络状态通知，detail = {info} | 1.9.0 | |
| binderror | eventhandle | 否 | 渲染错误事件，detail = {errMsg, errCode} | 1.7.4 | |
| bindbgmstart | eventhandle | 否 | 背景音开始播放时触发 | 2.4.0 | |
| bindbgmprogress | eventhandle | 否 | 背景音进度变化时触发，detail = {progress, duration} | 2.4.0 | |
| bindbgmcomplete | eventhandle | 否 | 背景音播放完成时触发 | 2.4.0 | |
| bindaudiovolumenotify | eventhandle | 否 | 返回麦克风采集的音量大小 | 2.12.0 |
orientation 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| vertical | 竖直 | |
| horizontal | 水平 |
local-mirror 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| auto | 前置摄像头镜像，后置摄像头不镜像 | |
| enable | 前后置摄像头均镜像 | |
| disable | 前后置摄像头均不镜像 |
audio-reverb-type 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| 0 | 关闭 | |
| 1 | KTV | |
| 2 | 小房间 | |
| 3 | 大会堂 | |
| 4 | 低沉 | |
| 5 | 洪亮 | |
| 6 | 金属声 | |
| 7 | 磁性 |
audio-volume-type 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| auto | 自动 | |
| media | 媒体音量 | |
| voicecall | 通话音量 |
beauty-style 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| smooth | 光滑美颜 | |
| nature | 自然美颜 |
filter 的合法值
| 值 | 说明 | 最低版本 |
|---|---|---|
| standard | 标准 | |
| pink | 粉嫩 | |
| nostalgia | 怀旧 | |
| blues | 蓝调 | |
| romantic | 浪漫 | |
| cool | 清凉 | |
| fresher | 清新 | |
| solor | 日系 | |
| aestheticism | 唯美 | |
| whitening | 美白 | |
| cerisered | 樱红 |
video
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| src | string | 是 | 要播放视频的资源地址，支持网络路径、本地临时路径、云文件ID（2.3.0） | 1.0.0 | |
| duration | number | 否 | 指定视频时长 | 1.1.0 | |
| controls | boolean | true | 否 | 是否显示默认播放控件（播放/暂停按钮、播放进度、时间） | 1.0.0 |
| danmu-list | Array.<object> | 否 | 弹幕列表 | 1.0.0 | |
| danmu-btn | boolean | false | 否 | 是否显示弹幕按钮，只在初始化时有效，不能动态变更 | 1.0.0 |
| enable-danmu | boolean | false | 否 | 是否展示弹幕，只在初始化时有效，不能动态变更 | 1.0.0 |
| autoplay | boolean | false | 否 | 是否自动播放 | 1.0.0 |
| loop | boolean | false | 否 | 是否循环播放 | 不支持 |
| muted | boolean | false | 否 | 是否静音播放 | 不支持 |
| initial-time | number | 0 | 否 | 指定视频初始播放位置 | 不支持 |
| page-gesture | boolean | false | 否 | 在非全屏模式下，是否开启亮度与音量调节手势（废弃，见 vslide-gesture） | 不支持 |
| direction | number | 否 | 设置全屏时视频的方向，不指定则根据宽高比自动判断 | 不支持 | |
| show-progress | boolean | true | 否 | 若不设置，宽度大于240时才会显示 | 不支持 |
| show-fullscreen-btn | boolean | true | 否 | 是否显示全屏按钮 | 不支持 |
| show-play-btn | boolean | true | 否 | 是否显示视频底部控制栏的播放按钮 | 不支持 |
| show-center-play-btn | boolean | true | 否 | 是否显示视频中间的播放按钮 | 不支持 |
| enable-progress-gesture | boolean | true | 否 | 是否开启控制进度的手势 | 不支持 |
| object-fit | string | contain | 否 | 当视频大小与 video 容器大小不一致时，视频的表现形式 | 1.0.0 |
| poster | string | 否 | 视频封面的图片网络资源地址或云文件ID（2.3.0）。若 controls 属性值为 false 则设置 poster 无效 | 1.0.0 | |
| show-mute-btn | boolean | false | 否 | 是否显示静音按钮 | 不支持 |
| title | string | 否 | 视频的标题，全屏时在顶部展示 | 不支持 | |
| play-btn-position | string | bottom | 否 | 播放按钮的位置 | 不支持 |
| enable-play-gesture | boolean | false | 否 | 是否开启播放手势，即双击切换播放/暂停 | 不支持 |
| auto-pause-if-navigate | boolean | true | 否 | 当跳转到本小程序的其他页面时，是否自动暂停本页面的视频播放 | 不支持 |
| auto-pause-if-open-native | boolean | true | 否 | 当跳转到其它APP原生页面时，是否自动暂停本页面的视频 | 不支持 |
| vslide-gesture | boolean | false | 否 | 在非全屏模式下，是否开启亮度与音量调节手势（同 page-gesture） | 不支持 |
| vslide-gesture-in-fullscreen | boolean | true | 否 | 在全屏模式下，是否开启亮度与音量调节手势 | 不支持 |
| ad-unit-id | string | 是 | 视频前贴广告单元ID，更多详情可参考开放能力视频前贴广告 | 不支持 | |
| poster-for-crawler | string | 是 | 用于给搜索等场景作为视频封面展示，建议使用无播放 icon 的视频封面图，只支持网络地址 | 不支持 | |
| show-casting-button | boolean | false | 否 | 显示投屏按钮。Android 在同层渲染下生效，支持 DLNA 协议；iOS 支持 AirPlay 和 DLNA 协议 | 不支持 |
| picture-in-picture-mode | string/Array | 否 | 设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： ["push", "pop"]） | 不支持 | |
| picture-in-picture-show-progress | boolean | false | 否 | 是否在小窗模式下显示播放进度 | 不支持 |
| enable-auto-rotation | boolean | false | 否 | 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效 | 不支持 |
| show-screen-lock-button | boolean | false | 否 | 是否显示锁屏按钮，仅在全屏时显示，锁屏后控制栏的操作 | 不支持 |
| show-snapshot-button | boolean | false | 否 | 是否显示截屏按钮，仅在全屏时显示 | 不支持 |
| bindplay | eventhandle | 否 | 当开始/继续播放时触发play事件 | 1.0.0 | |
| bindpause | eventhandle | 否 | 当暂停播放时触发 pause 事件 | 1.0.0 | |
| bindended | eventhandle | 否 | 当播放到末尾时触发 ended 事件 | 1.0.0 | |
| bindtimeupdate | eventhandle | 否 | 播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次 | 1.0.0 | |
| bindfullscreenchange | eventhandle | 否 | 视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction 有效值为 vertical 或 horizontal | 1.0.0 | |
| bindwaiting | eventhandle | 否 | 视频出现缓冲时触发 | 不支持 | |
| binderror | eventhandle | 否 | 视频播放出错时触发 | 不支持 | |
| bindprogress | eventhandle | 否 | 加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比 | 不支持 | |
| bindloadedmetadata | eventhandle | 否 | 视频元数据加载完成时触发。event.detail = {width, height, duration} | 不支持 | |
| bindcontrolstoggle | eventhandle | 否 | 切换 controls 显示隐藏时触发。event.detail = {show} | 不支持 | |
| bindenterpictureinpicture | eventhandler | 否 | 播放器进入小窗 | 不支持 | |
| bindleavepictureinpicture | eventhandler | 否 | 播放器退出小窗 | 不支持 | |
| bindseekcomplete | eventhandler | 否 | seek 完成时触发 (position iOS 单位 s, Android 单位 ms) | 不支持 |
native-view
原生view容器
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| type | string | camera | 是 | 原生容器类型，设置只会不可改变 | |
| options | string | {} | 否 | 传递给原生组件的自定义参数，使用json数据string格式化结果 | |
| bindontask | eventhandle | 否 | 接收原生组件发送事件 |
示例代码
<native-view type="{{type}}" options="{{options}}" bindready="bindonready"></native-view>
注：如需全局监听native-view事件，参考 onCustomEvent API
camera
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| mode | string | normal | 否 | 应用模式，只在初始化时有效，不能动态变更 | |
| resolution | string | medium | 否 | 分辨率，不支持动态修改 | |
| device-position | string | back | 否 | 摄像头朝向 | |
| flash | string | auto | 否 | 闪光灯，值为auto, on, off | |
| frame-size | string | medium | 否 | 指定期望的相机帧数据尺寸 | |
| bindstop | eventhandle | 否 | 摄像头在非正常终止时触发，如退出后台等情况 | ||
| binderror | eventhandle | 否 | 用户不允许使用摄像头时触发 | ||
| bindinitdone | eventhandle | 否 | 相机初始化完成时触发，e.detail = {maxZoom} | ||
| bindscancode | eventhandle | 否 | 在扫码识别成功时触发，仅在 mode="scanCode" 时生效 |