veplayer-mp-wechat

VePlayer小程序播放器

小程序播放器微信原生版本

快速接入小程序播放器

只需三步：安装、构建 npm、代码引入、即可完成小程序播放器组件的使用。

安装

# npm
npm i veplayer-mp-wechat

# yarn 
yarn add veplayer-mp-wechat

构建 npm 包

请优先了解微信小程序官网对于 npm 支持 的介绍

点击开发者工具中的菜单栏：工具 --> 构建 npm

引入组件

参考自定义组件的引入方式

{
  "usingComponents": {
    "ve-video": "veplayer-mp-wechat"
  }
}

使用组件

1. url 方式播放

<view>
  <!-- 以下是对小程序播放器组件的引用 -->
  <ve-video
    id="videoContainer"
    mode="portrait"
    src="http://xxxx.mp4"
    picture-in-picture-mode="['push', 'pop']"
    muted
    loop
  ></ve-video>
</view>

2. vid + playAuthToken 方式播放

<view>
  <!-- 以下是对一个播放器组件的引用 -->
  <xgvideo
    id='xgVideo'
    className='xg-video'
    mode='small'
    playDomain='https://vod.volcengineapi.com'
    playAuthToken='*****************'
  ></xgvideo>
</view>

• playDomain是调用火山引擎视频点播OpenAPI的接口地址，业务方如果做了该接口的代理，可以替换成业务方的地址。
• playAuthToken是获取视频播放信息的临时凭证，由业务方服务端通过调用火山服务端SDK基于视频vid本地服务生成，具体生成参考火山引擎视频点播文档

组件属性

小程序播放器对video原生组件进行了封装，因此支持大部分的video属性配置。以下说明列出了新增属性及差异化属性，列出的部分中以 show- 开头的开关即影响原生组件又影响自定义UI，不在列表中的只影响原生组件：

Property	Type	Default	Required	Description
mode	'portrait' | 'landscape'	'landscape'	No	播放器支持竖屏(portrait)及横屏(landscape)两种播放UI模式。横屏模式偏向于普通的PC视频播放器UI，竖屏视频展示类似抖音等短视频播放模式。
componentId	string		NO	video组件的id，用于通过createVideoContext获取视频VideoContext，不传入则会随机生成一个id，此时视频VideoContext仅能通过组件上下文的getContext方法获取
src	string		YES
controls	'custom' | 'native'|'false'	'custom'	No	custom: 自定义UI，native: 原生组件UI，false: 完全关闭播放UI控件（包括自定义UI及原生组件UI），播放UI控件指loading状态、播控按钮、进度条、时间显示等
duration	number		No	根据官方文档说明，duration属性只是控制显示的时长，不会控制实际播放的时长。因此该属性不设置给原始video组件，只提供给自定义UI使用
show-center-play-btn	boolean		No	是否显示视频正中心的播放按钮
show-bottom-progress	boolean		No	是否展示底部进度条
bindplay	eventhandle		No	当开始/继续播放时触发play事件
bindpause	eventhandle		No	当暂停播放时触发 pause 事件
bindended	eventhandle		No	当播放到末尾时触发 ended 事件
bindtimeupdate	eventhandle		No	播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次
bindfullscreenchange	eventhandle		No	视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction 有效值为 vertical 或 horizontal
bindwaiting	eventhandle		No	视频出现缓冲时触发
binderror	eventhandle		No	视频播放出错时触发
bindprogress	eventhandle		No	加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比
bindloadedmetadata	eventhandle		No	视频元数据加载完成时触发。event.detail = {width, height, duration}
bindcontrolstoggle	eventhandle		No	切换 controls 显示隐藏时触发。event.detail = {show}
bindenterpictureinpicture	eventhandle		No	播放器进入小窗
bindleavepictureinpicture	eventhandle		No	播放器退出小窗
bindseeking	eventhandle		No	组件内部代理劫持VideoContext，VideoContext.seek 调用后会立即发送该事件，该事件非video自带事件，只支持 controls="custom" 时才对外发送
bindseekcomplete	eventhandle		No	seek 完成时触发 (position iOS 单位 s, Android 单位 ms)

PS. 原生组件支持的属性配置请参考官方文档：https://developers.weixin.qq.com/miniprogram/dev/component/video.html

组件接口

小程序播放器对VideoContext进行了封装，提供同原生接口一致的API。原生接口更多细节可阅读官网

const component = this.selectComponent("#videoContainer");
const player = component.getContext()

// 原生接口
player.play()
player.pause()
player.stop()
player.seek(10)
player.sendDanmu(Object data)
player.playbackRate(1)
player.requestFullScreen({ direction: 90 })
player.exitFullScreen()
player.exitPictureInPicture()
player.requestBackgroundPlayback()
player.exitBackgroundPlayback()

组件事件

小程序播放器对外支持两种方式的事件订阅形式：组件属性配置事件订阅或者通过组件对象进行事件订阅，请选择其中一种进行订阅，尽量不要两者混用。这两种方式在组件实例被从页面节点树移除(lifetimes->detached)时进行事件解绑，不需要业务单独关注事件泄漏问题

1. 组件属性订阅事件

请参见组件属性中bind开头的事件属性

2. 组件Context对象订阅事件

小程序播放器提供了接口可以获取player context，并可以对player添加事件订阅。具体方式如下：

const component = this.selectComponent("#videoContainer");
const player = component.getContext();

// 事件订阅
player.on('error', (e) => {
  console.log('event error:', e)
});
player.on('timeupdate', (e) => {
  const { currentTime, duration } = e.detail;
  console.log('event timeupdate:', currentTime, duration)
});
// ...

事件列表:

EventName	CustomEvent	Description
play	No	参见属性 bindplay 描述
pause	No	参见属性 bindpause 描述
ended	No	参见属性 bindended 描述
timeupdate	No	参见属性 bindtimeupdate 描述
fullscreenchange	No	参见属性 bindfullscreenchange 描述
waiting	No	参见属性 bindwaiting 描述
error	No	参见属性 binderror 描述
progress	No	参见属性 bindprogress 描述
loadedmetadata	No	参见属性 bindloadedmetadata 描述
controlstoggle	No	参见属性 bindcontrolstoggle 描述
enterpictureinpicture	No	参见属性 bindenterpictureinpicture 描述
leavepictureinpicture	No	参见属性 bindleavepictureinpicture 描述
seeking	Yes	参见属性 bindseeking 描述
seekcomplete	No	参见属性 bindseekcomplete 描述

uni-app 项目使用

此播放器组件提供的是原生小程序版本，uni-app项目支持使用小程序自定义组件，可以按照以下步骤在uni-app项目中使用此播放器组件：

1. 在uin-app项目中安装依赖：

# npm
npm i veplayer-mp-wechat

# yarn 
yarn add veplayer-mp-wechat

1. 拷贝node_modules/veplayer-mp-wechat到项目小程序组件存放目录wxcomponents。

2. 在 pages.json 对应页面的 style -> usingComponents 引入组件：

{
	"pages": [{
		"path": "index/index",
		"style": {
			// #ifdef APP-PLUS || H5 || MP-WEIXIN || MP-QQ
			"usingComponents": {
				"ve-video": "/wxcomponents/veplayer-mp-wechat/dist/index"
			},
			// #endif
			"navigationBarTitleText": "uni-app"
		}
	}]
}

1. 在页面中使用：

组件使用

<!-- 页面模板 (index.vue) -->
<view>
  <!-- 在页面中对自定义组件进行引用 -->
  <ve-video
    id="video"
    src="https://xx.cdn.com/demo.mp4"
    controls="custom"
  />
</view>

API使用，以暂停为例：

  const component = this.selectComponent('#video');
  const player = component.getContext();
  if (player) {
    player.pause();
  }

订阅事件：

  const component = this.selectComponent('#video');
  const player = component.getContext();
  if (player) {
    player.on('timeupdate', (e) => {
      const { currentTime, duration } = e.detail;
      console.log('event timeupdate:', currentTime, duration)
    });
  }

如果是从uni-app的video组件迁移到本组件，不作API使用的更改，则组件属性里通过componentId传入uni.createVideoContext需要的组件id，API调用同uni-app组件说明。需要注意的是通过createVideoContext获取的播放器上下文无法使用事件订阅。

1. 微信小程序构建

uni-app项目打包构建微信产物，用微信开发者工具导入打包后的产物，如果打包产物根目录里没有package.json，则执行npm init -y初始化npm，安装依赖npm i veplayer-mp-wechat或yarn add veplayer-mp-wechat，微信开发者工具 - 工具 - 构建npm，即完成了在微信小程序组件的构建。这样就可以通过微信开发者工具预览使用效果。