更新记录

2.0.1（2026-06-16）

增加使用说明

2.0.0（2026-06-16）

0.0.1

平台兼容性

uni-app(5.13)

uni-app x(5.13)

custom-video-player —— 跨平台原生视频播放插件

一款开箱即用的视频播放器组件，各平台底层走原生播放器，自带完整 UI 控件、手势交互，完整支持 0.5x ~ 2.0x 倍速播放。

适用于：教培视频、短视频 Feed、课程播放、直播回放等场景。

〇、运行要求（重要！）

由于本插件使用了 UTS 原生 SDK 调用各平台底层播放器（Android MediaPlayer、iOS AVPlayer 等），不同平台的运行方式不同：

如何制作自定义基座？

1. HBuilderX 菜单 → 运行 → 运行到手机或模拟器 → 制作自定义基座
2. 选择目标平台（Android / iOS），等待打包完成
3. 打包完成后，再次 运行 → 运行到手机或模拟器，选择刚刚制作的自定义基座即可

小白提示：如果你是第一次开发，建议先在 Web（浏览器） 上调试，无需任何配置，效果和真机一致。等逻辑调通后再打自定义基座跑真机。

一、快速上手（1 分钟）

1. 导入组件

<template>
  <custom-video-player
    ref="playerRef"
    src="https://www.w3schools.com/html/mov_bbb.mp4"
    :autoplay="true"
    :show-mute-btn="true"
    @timeupdate=""
  />
</template>

<script lang="uts" setup>
import CustomVideoPlayer from '@/uni_modules/custom-video-player/components/custom-video-player/custom-video-player.uvue'

const playerRef = ref<any>(null)

function (e: { currentTime: number; duration: number }) {
  console.log('进度:', e.currentTime.toFixed(1), '/', e.duration.toFixed(1))
}
</script>

这就行了——组件自动处理：原生播放器创建、控件渲染、手势交互、全屏切换、倍速菜单。你只需传入 src 即可播放。

2. 通过 ref 控制播放

// 播放 / 暂停
playerRef.value.play()
playerRef.value.pause()

// 跳转到第 30 秒
playerRef.value.seek(30)

// 切换到 1.5 倍速
playerRef.value.setRate(1.5)

// 进入全屏
playerRef.value.requestFullScreen()

// 读取当前状态
const state = playerRef.value.getState()
console.log(state.currentTime, state.duration, state.isPlaying)

二、运行 Demo

项目内置了完整的调试 Demo 页面，推荐先跑起来看看效果：

页面路径：pages/VideoSub/videoPlayerDemo

或在 pages.json 中跳转：

{ "path": "pages/VideoSub/videoPlayerDemo" }

Demo 提供：

• 多视频源切换
• 所有 Props 实时开关
• 手势操作演示
• 全事件日志输出

三、Props（组件属性）

基础属性

控件显隐

手势控制

其他

使用示例

<custom-video-player
  src="https://example.com/video.mp4"
  poster="https://example.com/cover.jpg"
  :autoplay="true"
  :loop="false"
  :muted="false"
  :default-rate="1.0"
  object-fit="contain"
  title="我的视频"
  :show-mute-btn="true"
  :show-back-btn="true"
  :enable-progress-gesture="true"
  :enable-play-gesture="true"
/>

四、Events（事件）

所有事件名对齐 uni-app / 微信小程序 VideoContext，可直接迁移。

state 取值说明

使用示例

<custom-video-player
  src="..."
  @ready="onReady"
  @play="onPlay"
  @pause="onPause"
  @timeupdate=""
  @state="onState"
  @load="onLoad"
  @error="onError"
  @back="onBack"
  @ratechange=""
  @buffering="onBuffering"
  @fullscreen="onFullscreen"
/>

function onReady() { console.log('可以播放了') }
function onPlay() { console.log('开始播放') }
function onPause() { console.log('暂停了') }

function (e: { currentTime: number; duration: number }) {
  // 更新进度条
  progress.value = (e.currentTime / e.duration) * 100
}

function onLoad(e: { width: number; height: number; duration: number }) {
  console.log(`视频尺寸 ${e.width}x${e.height}，时长 ${e.duration}s`)
}

function onError(e: { errMsg: string }) {
  uni.showToast({ title: '播放失败: ' + e.errMsg, icon: 'none' })
}

function onBack() {
  // 自定义返回逻辑；返回按钮也可通过 show-back-btn="false" 隐藏
  uni.navigateBack()
}

五、Ref API（通过 ref 调用组件方法）

组件暴露了完整的方法供外部控制：

getState() 返回值

{
  currentTime: number    // 当前播放秒数
  duration: number       // 总时长
  rate: number           // 当前倍速
  isPlaying: boolean     // 是否正在播放
  isFullscreen: boolean  // 是否全屏
  isPiP: boolean         // 是否画中画
  videoWidth: number     // 视频宽度（暂未实现）
  videoHeight: number    // 视频高度（暂未实现）
}

使用示例

const playerRef = ref<any>(null)

// 播放控制
playerRef.value.play()
playerRef.value.pause()
playerRef.value.seek(60)           // 跳到 1 分钟

// 倍速切换
playerRef.value.setRate(2.0)       // 2 倍速

// 全屏
playerRef.value.requestFullScreen(90)  // 横屏全屏

// 画中画（Android）
playerRef.value.togglePiP()

// 读取进度
const state = playerRef.value.getState()
console.log(`${state.currentTime}/${state.duration}`)

六、手势交互

组件内置以下手势，无需额外代码：

手势可通过 Props 关闭：

<custom-video-player
  :enable-play-gesture="false"       <!-- 关闭双击 -->
  :enable-progress-gesture="false"   <!-- 关闭水平滑动 -->
/>

七、控件自动隐藏

播放时，底部控制栏和顶部标题栏会在 3 秒无操作后自动隐藏，触摸视频画面即可重新显示。

• 暂停状态下控件始终显示
• 视频未开始播放时控件始终显示
• 触摸视频画面可以随时唤醒控件

八、完整使用示例

一个包含常用功能的完整示例：

<template>
  <view style="flex:1">
    <custom-video-player
      ref="playerRef"
      :src="videoUrl"
      :poster="posterUrl"
      :title="videoTitle"
      :autoplay="false"
      :default-rate="1.0"
      object-fit="contain"
      :show-mute-btn="true"
      :show-back-btn="true"
      :enable-play-gesture="true"
      :enable-progress-gesture="true"
      @ready="onReady"
      @play="onPlay"
      @pause="onPause"
      @timeupdate=""
      @error="onError"
      @back="onBack"
    />
  </view>
</template>

<script lang="uts" setup>
import CustomVideoPlayer from '@/uni_modules/custom-video-player/components/custom-video-player/custom-video-player.uvue'

const playerRef = ref<any>(null)
const videoUrl = ref('https://www.w3schools.com/html/mov_bbb.mp4')
const posterUrl = ref('')
const videoTitle = ref('示例视频')

function onReady() {
  console.log('播放器就绪')
}

function onPlay() {
  console.log('正在播放')
}

function onPause() {
  console.log('已暂停')
}

function (e: { currentTime: number; duration: number }) {
  // 业务逻辑，比如记录学习进度
  const progress = e.duration > 0 ? (e.currentTime / e.duration) * 100 : 0
  console.log('进度:', progress.toFixed(1) + '%')
}

function onError(e: { errMsg: string }) {
  uni.showToast({ title: '播放失败', icon: 'none' })
}

function onBack() {
  uni.navigateBack()
}
</script>

九、目录结构

uni_modules/custom-video-player/
├── package.json
├── readme.md                          ← 你正在看的文档
├── utssdk/
│   ├── interface.uts                  # 统一接口定义（类型 + API 契约）
│   ├── app-android/index.uts          # Android: MediaPlayer + SurfaceView
│   ├── app-ios/index.uts              # iOS: AVPlayer + AVPlayerLayer
│   ├── app-harmony/index.uts          # 鸿蒙: AVPlayer + XComponent
│   ├── web/index.uts                  # Web: HTML5 video
│   └── mp-weixin/index.uts            # 微信小程序: video 组件
└── components/
    └── custom-video-player/
        └── custom-video-player.uvue   # 统一组件层（跨平台 UI）

十、各平台原生实现

十一、注意事项

1. 视频源要求

• 推荐使用 HTTPS 地址
• 支持格式：MP4、M3U8（各平台兼容性有差异）
• 本地路径请使用 @/static/xxx.mp4 或 /static/xxx.mp4

2. 倍速生效时机

建议： 先调用 play()，再调用 setRate()，确保倍速在各平台生效。

3. Android API 版本

• MediaPlayer.setPlaybackParams() 需要 API 23+（Android 6.0）
• 低版本设备不支持倍速，会降级为正常速度

4. 直播场景

• 直播流（如 M3U8）不设置 duration，进度条会自动适配
• 微信小程序端 M3U8 需基础库版本 ≥ 2.0.0

5. 多实例

同一页面可放多个 <custom-video-player>，通过 video-id 区分：

<custom-video-player video-id="player1" src="..." />
<custom-video-player video-id="player2" src="..." />

不传 video-id 时组件自动生成唯一 ID。

6. 画中画 / 后台音频

• togglePiP() 目前仅在 Android 平台有原生实现
• toggleBackgroundAudio() 用于启用锁屏信息 + 后台音频播放（Android/iOS）
• 其他平台调用这些方法不会崩溃，只是无效果

十二、常见问题

Q: 如何隐藏所有控件，只显示视频画面？

<custom-video-player
  :show-controls="false"
  :show-center-play-btn="false"
  :enable-play-gesture="false"
  :enable-progress-gesture="false"
/>

Q: 如何获取当前播放进度？

两种方式：

1. 监听 @timeupdate 事件
2. 主动调用 playerRef.value.getState().currentTime

Q: 视频加载失败怎么处理？

监听 @error 事件，组件会自动显示"播放失败，点击重试"的 UI。

Q: 如何在微信小程序中使用？

直接引入组件即可——底层自动切换为微信 <video> 组件 + VideoContext，无需额外配置。

Q: 如何自定义倍速列表？

目前固定为 0.5x / 1.0x / 1.25x / 1.5x / 2.0x。如需自定义，可修改组件中 availableRates 常量：custom-video-player.uvue 第 148 行。