小程序框架组件之媒体组件

媒体组件（详情可见微信开发文档。）主要用来显示图片、播放音频，以及直播等

image（图片）

一个应用中图片是必不可少的，就像HTML提供了标签一样，小程序提供了组件。小程序中的除了可以显示图片外，还提供了图片的裁剪、缩放两种模式。持 JPG、PNG、SVG、WEBP、GIF 等格式，2.3.0 起支持云文件ID。需要注意的是：image组件默认的宽度为300px、高度225px；image组件中二维码（小图片）不支持长按识别。image组件属性如下：

属性	类型	默认值	必填	说明	最低版本
src	string		否	图片资源地址。可以是网络地址，也可以是本地图片的相对地址	1.0.0
mode	string	scaleToFill	否	图片裁剪、缩放的模式	1.0.0
webp	boolean	false	否	默认不解析 webP 格式，只支持网络资源	2.9.0
lazy-load	boolean	false	否	图片懒加载，只针对page与scroll-view下的Image有效；在即将进入一定范围（上下三屏）时才开始加载	1.5.0
show-menu-by-longpress	boolean	false	否	开启长按图片显示识别小程序码菜单	2.7.0
binderror	eventhandle		否	当错误发生时触发，event.detail = {errMsg}	1.0.0
bindload	eventhandle		否	当图片载入完毕时触发，event.detail = {height, width}	1.0.0

mode 属性一共有13种模式，其中四种4种是缩放模式，9种是裁剪模式。mode的合法值如下：

值	说明
scaleToFill	缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
aspectFit	缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
aspectFill	缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
widthFix	缩放模式，宽度不变，高度自动变化，保持原图宽高比不变
heightFix	缩放模式，高度不变，宽度自动变化，保持原图宽高比不变

裁剪模式：

值	说明
top	裁剪模式，不缩放图片，只显示图片的顶部区域
bottom	裁剪模式，不缩放图片，只显示图片的底部区域
center	裁剪模式，不缩放图片，只显示图片的中间区域
left	裁剪模式，不缩放图片，只显示图片的左边区域
right	裁剪模式，不缩放图片，只显示图片的右边区域
top left	裁剪模式，不缩放图片，只显示图片的左上边区域
top right	裁剪模式，不缩放图片，只显示图片的右上边区域
bottom left	裁剪模式，不缩放图片，只显示图片的左下边区域
bottom right	裁剪模式，不缩放图片，只显示图片的右下边区域

audio（音频）

audio组件从小程序基础库1.6.0版本开始，不再维护该组件。建议使用能力更强的wx.createInnerAudioContext接口。该组件属性如下：

属性	类型	默认值	必填	说明	最低版本
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

video（视频）

该组件是原生组件，使用时请注意相关限制（原生组件说明）。视频组件默认宽度是300px、高度225px，可通过wxss设置宽和高。该组件属性如下：

属性	类型	默认值	必填	说明	最低版本
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	否	是否循环播放	1.4.0
muted	boolean	false	否	是否静音播放	1.4.0
initial-time	number	0	否	指定视频初始播放位置	1.6.0
page-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（废弃，见 vslide-gesture）	1.6.0
direction	number	否	设置全屏时视频的方向，不指定则根据宽高比自动判断	1.7.0
show-progress	boolean	true	否	若不设置，宽度大于240时才会显示	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	否	是否开启控制进度的手势	1.9.0
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	否	是否显示静音按钮	2.4.0
title	string		否	视频的标题，全屏时在顶部展示	2.4.0
play-btn-position	string	bottom	否	播放按钮的位置	2.4.0
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停	2.4.0
auto-pause-if-navigate	boolean	true	否	当跳转到本小程序的其他页面时，是否自动暂停本页面的视频播放	2.5.0
auto-pause-if-open-native	boolean	true	否	当跳转到其它微信原生页面时，是否自动暂停本页面的视频	2.5.0
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（同 page-gesture）	2.6.2
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势	2.6.2
ad-unit-id	string		是	视频前贴广告单元ID，更多详情可参考开放能力视频前贴广告	2.8.1
poster-for-crawler	string		是	用于给搜索等场景作为视频封面展示，建议使用无播放 icon 的视频封面图，只支持网络地址
show-casting-button	boolean	false	否	显示投屏按钮。只安卓且同层渲染下生效，支持 DLNA 协议	2.10.2
picture-in-picture-mode	string/Array		否	设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： [“push”, “pop”]）	2.11.0
picture-in-picture-show-progress	boolean	false	否	是否在小窗模式下显示播放进度	2.11.0
enable-auto-rotation	boolean	false	否	是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效	2.11.0
show-screen-lock-button	boolean	false	否	是否显示锁屏按钮，仅在全屏时显示，锁屏后控制栏的操作	2.11.0
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.4.0
bindwaiting	eventhandle		否	视频出现缓冲时触发	1.7.0
binderror	eventhandle		否	视频播放出错时触发	1.7.0
bindprogress	eventhandle		否	加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比	2.4.0
bindloadedmetadata	eventhandle		否	视频元数据加载完成时触发。event.detail = {width, height, duration}	2.7.0
bindcontrolstoggle	eventhandle		否	切换 controls 显示隐藏时触发。event.detail = {show}	2.9.5
bindenterpictureinpicture	eventhandler		否	播放器进入小窗	2.11.0
bindleavepictureinpicture	eventhandler		否	播放器退出小窗	2.11.0

direction 的合法值

值	说明
0	正常竖向
90	屏幕逆时针90度
-90	屏幕顺时针90度

camera（相机）

相机（camera），从基础库1.6.0开始支持，低版本需要做兼容处理。该组件是原生组件，使用时请注意相关限制（原生组件说明）。扫描二维码功能，需要升级微信客户端至6.7.3。需要注意的是：相机组件使用时需要用户授权scope.camera，再就是同一个页面只能插入一个camera组件。该组件属性如下：

属性	类型	默认值	必填	说明	最低版本
mode	string	normal	否	应用模式，只在初始化时有效，不能动态变更	2.1.0
resolution	string	medium	否	分辨率，不支持动态修改	2.10.0
device-position	string	back	否	摄像头朝向	1.0.0
flash	string	auto	否	闪光灯，值为auto, on, off	1.0.0
frame-size	string	medium	否	指定期望的相机帧数据尺寸	2.7.0
bindstop	eventhandle		否	摄像头在非正常终止时触发，如退出后台等情况 1.0.0
binderror	eventhandle		否	用户不允许使用摄像头时触发	1.0.0
bindinitdone	eventhandle		否	相机初始化完成时触发，e.detail = {maxZoom}	2.7.0
bindscancode	eventhandle		否	在扫码识别成功时触发，仅在 mode=“scanCode” 时生效	2.1.0

mode 的合法值

值	说明
normal	相机模式
scanCode	扫码模式

live-player（实时音频）

该组件是原生组件，使用时请注意相关限制（原生组件说明）。它从基础库1.7.0开始支持，低版本需要做兼容处理。这两年比较热门的直播也可以用小程序来实现，该组件即可用来实现直播流媒体的实时播放。直播功能组件目前需要进行相关的审核才可以开通该组件的权限。相关api：wx.createLivePlayerContext




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 时表示没有任何抖动，值越大表明网络抖动越大，网络越不稳定
videoWidth	视频画面的宽度
videoHeight	视频画面的高度

小窗特性说明
live-player 小窗支持以下三种触发模式（在组件上设置 picture-in-picture-mode 属性）：

push 模式，即从当前页跳转至下一页时出现小窗（页面栈push）

pop 模式，即离开当页面时触发（页面栈pop）

以上两种路由行为均触发小窗

此外，小窗还支持以下特性：

小窗容器尺寸会根据原组件尺寸自动判断

点击小窗，用户会被导航回小窗对应的播放器页面

小窗出现后，用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

当播放器进入小窗模式后，播放器所在页面处于 hide 状态(触发 onHide 生命周期)，该页面不会被销毁。当小窗被关闭时，播放器所在页面会被 unload (触发 onUnload 生命周期)。

注意：
1、live-player 默认宽度300px、高度225px，可通过wxss设置宽高。
2、开发者工具上暂不支持。
3、相关介绍和原理可参考此文章
示例代码
在开发者工具中预览效果

Page({
  statechange(e) {
    console.log('live-player code:', e.detail.code)
  },
  error(e) {
    console.error('live-player error:', e.detail.errMsg)
  }
})

live-pusher（实时音频录制）

该组件是原生组件，使用时请注意相关限制（原生组件说明）。它从基础库1.7.0开始支持，低版本需要做兼容处理。使用该组件需要用户授权 scope.camera、scope.record。
该组件实现直播推流。相关api：wx.createLivePusherContext
属性详情可见微信小程序开发文档：

（实在不想写了，好多啊，处于厌学状态的一天！！！）