文档中心

视频点播

小程序播放器 SDK

集成微信小程序 SDK

视频点播提供微信小程序播放器 SDK，具有丰富的播放控制功能和良好的用户交互体验，可帮助您实现所需的业务功能。SDK 还支持播放日志上报功能，用于统计播放量、播放失败率、首帧时间、卡顿率等播放指标。搭配质量平台，您可以进行精细化的指标统计、实时的数据监控和深入的指标分析。

前提条件

在小程序后台 > 开发 > 开发设置 > 服务器域名中添加日志上报域名：https://mcs.zijieapi.com。操作截图示例如下。
说明
视频资源的 CDN 域名不需要添加到域名配置中。
在视频点播控制台新建应用并获取应用 ID。具体步骤请见应用管理。

添加依赖

通过 npm 添加以下依赖：

# npm
npm i veplayer-mp-wechat # 播放器 SDK

# yarn 
yarn add veplayer-mp-wechat // 播放器 SDK

构建 npm 包

说明

构建前，请先了解微信小程序官网对于 npm 支持的介绍。

单击微信开发者工具菜单栏中的工具 > 构建 npm。

引入组件

详情请参考微信官方文档小程序自定义组件的引入方式。请在使用播放器的页面或自定义组件的 .json 配置文件（例如 pages/index/index.json）中添加以下 usingComponents 配置：

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

使用组件

使用播放器组件

在对应页面或自定义组件的 .wxml 文件（例如 pages/index/index.wxml）中添加以下播放器模板。

<view>
  <!-- 以下是对小程序播放器 SDK 的引用 -->
  <veplayer
    id="videoContainer"
    showPlayBtn
    autoplay
    src="{{src}}"
    logInfo="{{logInfo}}"
    bindplay="onPlay"
  />
</view>

您需要对应业务组件中添加日志上报所需的配置，如下表所示：

属性名	类型	是否必选	默认值	说明
appId	Number	是	`-`	应用 ID。可在火山引擎视频点播控制台上获取应用 ID，具体步骤请见应用管理。
userId	String	否	`-`	用户 ID。强烈建议您使用与业务密切相关的用户 ID，以便在播放过程中出现错误时，可以进行单点故障排查，精确定位问题。如果您没有设定用户 ID，SDK 将随机生成一个值。
tag	String	否	`-`	业务标签或业务类型，用于标记不同的播放场景，如推荐页、详情页。
subTag	String	否	`-`	子业务标签或业务类型，用于细分播放场景。
vtype	HLS 或 MP4	否	MP4	视频格式
codecType	String	否	h264	视频编码格式
bitrate	Number	否	0	视频码率
appName	String	否	小程序	应用名称
appVersion	String	否	1.0.0	应用版本

代码示例如下：

// index.js
Component({
  data: {
    src: '<YOUR_VIDEO_URL>', // 替换为实际可访问的视频播放 URL
    // 配置日志上报
    logInfo: {
      appId: xxx,
      userId: "xxx",
      tag: 'recommend',
      subTag: 'hot',
    }
  }
})

查看日志上报数据

视频信息配置完成后，查看日志上报数据的操作步骤如下：

登录视频点播控制台。
单击左侧导航栏质量平台 > 播放看板，进入播放看板页面，选择大盘速览页签。
在查询条件中选择微信小程序。详细操作说明请见查看大盘速览。
注意
小程序播放质量数据仅采集真机 Android 和 iOS 系统的数据。
- 一般情况下，数据延时为 5～10 分钟。
- 如果发现过去很久没有看到数据，可能的原因为您通过开发者工具模拟器、桌面端微信播放的小程序数据均会被过滤。

组件属性

小程序播放器封装了 video 原生组件，支持配置大部分的 video 属性。原生组件支持的属性配置详情请参考微信官方文档。以下列表展示了新增属性及差异化属性。

说明

列表中的部分属性以 show- 开头的开关，既影响原生组件，又影响自定义 UI。
不在列表中的只影响原生组件。
原生微信 video 组件的属性，如：show-play-btn 这类中划线分割的属性名，需要改写成驼峰式命名showPlayBtn。

属性	类型	默认值	是否必选	说明
mode	Enum	`landscape`	否	UI 模式。支持 2 种播放 UI 模式。取值如下： `portrait`：竖屏。展示偏向于普通的 PC 视频播放器 UI 模式。（默认值）`landscape`：横屏。展示类似抖音等短视频播放 UI 模式。
disableLogVerify	Boolean	`false`	否	关闭日志配置验证。取值如下： `false`：否。如果没有配置日志，则会播放器报错。 `true`：是。关闭日志配置验证。
componentId	String	`-`	否	video 组件 ID。通过`createVideoContext`获取视频 VideoContext。不传，随机生成一个 ID，通过组件上下文的`getContext()`方法获取视频 VideoContext。
logInfo	Object	`-`	否	日志上报时用到的视频信息
src	String	`-`	是	播放视频的资源地址。支持网络路径、本地临时路径、存储在微信服务的文件 ID 等。
controls	Enum	`custom`	否	播控 UI 的模式。取值如下： `'custom'`：自定义 UI。 `'native'`：原生组件 UI。 `false`：完全关闭播放 UI 控件（包括自定义 UI 及原生组件UI）。 `'focus'`：高亮状态。 `'hidden'`：隐藏状态（禁交互）。 `'blur'`：失去焦点状态。 `'immerse'`：半沉浸状态（即半透明状态）。说明半沉浸态是指播放器的播控从激活态 `focus` 变为失焦态时，不转为隐藏状态，而是变为半隐藏状态，该状态可以方便地提醒用户播控并没有消失，同时不影响内容观看。播放 UI 控件指 loading 状态、播控按钮、进度条、时间显示等。
playBtnPosition	Enum	`bottom`	否	播放按钮的位置。取值如下： `center`：视频中间。 `bottom`：控制条上。 `center-bottom`：底部居中。说明仅当 `controls` 取值为非 `'native'` 和 `false` 时，生效。
duration	number	`-`	否	指定视频时长。说明不会控制实际播放的时长。因此该属性不设置给原始 video 组件，只提供给自定义 UI 使用。
showCenterPlayBtn	Boolean	`true`	否	是否显示视频正中心的播放按钮。取值如下： `true`：是 `false`：否
showBottomProgress	Boolean	`true`	否	是否展示底部进度条。取值如下： `true`：是 `false`：否
needLoading	Boolean	`true`	否	是否显示 loading 加载标识。说明当 `controls` 属性取值为 `custom` 时，该 `needLoading` 属性生效。 v0.1.12 之后的版本生效。
timeUpdateInterval	Number	400	否	进度条更新的频率，单位为 ms。用于减少频繁的渲染造成内存升高的问题。
autoBlurTime	Number	15000	否	自动失焦，即播放器在处于激活态，用户无操作多长时间隐藏播控。
interactiveConfig	Object	`-`	否	响应式配置。支持以下参数： `immersive`：是否启用半沉浸式。默认值为 false。 `delay`：进入半沉浸状态/隐藏状态的延迟时间，单位为 ms。默认值为 10000。 `focusDelay`：隐藏态进入 focus 态是否自动切换，单位为 ms。默认值为 0。
enableTapActive	Boolean	true	否	是否启用点击触发激活（进入 `focus` 态）。说明当自定义 `controls` 时，取值不是 `native` 时，该 `enableTapActive` 属性才生效。
bindplay	Eventhandle	`-`	否	当开始/继续播放时触发 `play` 事件。
bindpause	Eventhandle	`-`	否	当暂停播放时触发 `pause` 事件。
bindended	Eventhandle	`-`	否	当播放到末尾时触发 `ended` 事件。
bindtimeupdate	Eventhandle	`-`	否	播放进度变化时触发 `timeupdate` 事件。 `event.detail = {currentTime, duration};` 触发频率 250ms 一次。
bindfullscreenchange	Eventhandle	`-`	否	视频进入和退出全屏时触发 `fullscreenchange` 事件。 `event.detail = {fullScreen, direction} // direction 有效值为 vertical 或 horizontal`
bindwaiting	Eventhandle	`-`	否	视频出现缓冲时触发 `waiting` 事件。
binderror	Eventhandle	`-`	否	视频播放出错时触发 `error`事件。
bindprogress	Eventhandle	`-`	否	加载进度变化时触发 `progress` 事件，只支持一段加载。 `event.detail = {buffered} // 百分比`
bindloadedmetadata	Eventhandle	`-`	否	视频元数据加载完成时触发 `loadedmetadata` 事件。 `event.detail = {width, height, duration}`
bindcontrolstoggle	Eventhandle	`-`	否	切换 `controls` 显示隐藏时触发 `controlstoggle` 事件。 `event.detail = {show}`
bindenterpictureinpicture	Eventhandle	`-`	否	播放器进入小窗 `enterpictureinpicture` 事件。
bindleavepictureinpicture	Eventhandle	`-`	否	播放器退出小窗 `leavepictureinpicture` 事件。
bindseekcomplete	Eventhandle	`-`	否	seek 完成时触发 `seekcomplete` 事件。说明 `position` 的单位区别如下：系统类型为 iOS，单位为 s。系统类型为 Android，单位为 ms。
binduseraction	Eventhandle	`-`	否	用户行为触发。例如，用户点击暂停、滑动进度条。

组件接口

小程序播放器封装了 VideoContext，提供同原生接口一致的 API。代码示例如下所示。

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

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

组件事件

微信小程序播放器对外支持 2 种方式的事件监听形式：

组件属性 bind 方式事件监听
组件对象提供事件订阅的机制进行事件监听

请选择其中一种进行订阅，尽量不要两者混用。这两种方式在组件实例中，被从页面节点树移除(lifetimes->detached)时，进行事件解绑，您无需单独关注事件泄漏的问题。

组件属性 bind 方式事件监听

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

组件对象提供事件订阅的机制进行事件监听

小程序播放器提供了接口可以获取 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)
});
// ...

详细的事件列表如下所示。

事件名称	是否可自定义事件	说明
play	否	当开始/继续播放时触发 `play` 事件。
pause	否	当暂停播放时触发 `pause` 事件。
ended	否	当播放到末尾时触发 `ended` 事件。
timeupdate	否	播放进度变化时触发。
fullscreenchange	否	视频进入和退出全屏时触发 `fullscreenchange` 事件。
waiting	否	视频出现缓冲时触发 `waiting` 事件。
error	否	视频播放出错时触发 `error` 事件。
progress	否	加载进度变化时触发 `progress` 事件，只支持一段加载。
loadedmetadata	否	视频元数据加载完成时触发 `loadedmetadata` 事件。
controlstoggle	否	切换 `controls` 显示隐藏时触发 `controlstoggle` 事件。
enterpictureinpicture	否	播放器进入小窗 `enterpictureinpicture` 事件。
leavepictureinpicture	否	播放器退出小窗 `leavepictureinpicture` 事件。
seekcomplete	否	seek 完成时触发 `seekcomplete` 事件。
controlstoggle	否	切换 `controls` 显示隐藏时触发 `controlstoggle` 事件。
useraction	是	用户行为触发，如用户点击暂停、滑动进度条。

最近更新时间：2026.10.21 13:20:23

这个页面对您有帮助吗？

有用

无用

视频点播

前提条件 #

添加依赖 #

构建 npm 包 #

引入组件 #

使用组件 #

使用播放器组件 #

查看日志上报数据 #

组件属性 #

组件接口 #

组件事件 #

组件属性 bind 方式事件监听 #

组件对象提供事件订阅的机制进行事件监听 #