鸿蒙平台uni-app x视频播放video组件开发属性事件全屏适配避坑

鸿蒙专家

在鸿蒙平台做 uni-app x 视频播放，video 组件是标准方案，HarmonyOS 4.61 开始支持。它支持本地与网络视频，自带播放/暂停、进度条、全屏按钮，还能做全屏、弹幕、倍速、小窗播放和投屏。鸿蒙端底层使用 ArkUI 的 Video 组件原生实现，因此播放流畅、系统解码支持较好；代价是格式与能力受平台约束，支持 mp4、m4v、mov、3gp、flv、m3u8，本地 m3u8 文件不支持。

一、核心属性与事件

video 的属性很多，实际开发先掌握 src、controls、object-fit、poster、muted、autoplay、loop、show-controls、show-fullscreen-btn、show-center-play-btn、direction 等。object-fit 控制视频缩放方式，类似 image 的 mode。常用事件包括 play、pause、ended、timeupdate、progress、fullscreenchange、error，以及 list-view 下的 recycle、reuse。

基础写法：

2. <template>
3.   <video src='' style='width: 100%; height: 250px;'></video>
4. </template>

复制代码

二、典型场景拆解

1. 基础播放与状态监听

2. <template>
3.   <view style='padding: 15px;'>
4.     <video src='' style='width: 100%; height: 250px;' @play='onPlay' @pause='onPause' @ended='onEnded'></video>
5.   </view>
6. </template>
7. <script setup lang='uts'>
8. const onPlay = () => { console.log('开始播放') }
9. const onPause = () => { console.log('暂停播放') }
10. const onEnded = () => { console.log('播放结束') }
11. </script>

复制代码

2. 封面和全屏标题
poster 设置封面图片，title 设置全屏时顶部显示的标题。注意 poster 只支持网络地址，不支持本地路径；如果 controls=false，poster 不会显示，需要自己用 image 组件覆盖实现封面。

2. <video src='' poster='封面网络地址' title='视频标题' :show-fullscreen-btn='true' style='width: 100%; height: 250px;'></video>

复制代码

3. 自动播放与循环
短视频常用 autoplay + loop + muted。muted 必须为 true，否则很多浏览器和平台不允许自动播放。

2. <video src='' :autoplay='true' :loop='true' :muted='true' :show-controls='false' object-fit='cover' style='width: 100%; height: 400px;'></video>

复制代码

4. 播放进度与缓冲进度
@timeupdate 每 250ms 触发一次，可取得当前播放进度；@progress 可取得缓冲进度。若在 timeupdate 里做复杂计算，可能影响性能。

2. <template>
3.   <view style='padding: 15px;'>
4.     <video id='myVideo' src='' style='width: 100%; height: 250px;' @timeupdate='onTimeUpdate' @progress='onProgress'></video>
5.     <text>播放进度：{{currentTime}}s / {{duration}}s</text>
6.     <text>缓冲进度：{{buffered}}%</text>
7.   </view>
8. </template>
9. <script setup lang='uts'>
10. const currentTime = ref(0)
11. const duration = ref(0)
12. const buffered = ref(0)
13. const onTimeUpdate = (event: UniVideoTimeUpdateEvent) => {
14.   currentTime.value = Math.floor(event.detail.currentTime)
15.   duration.value = Math.floor(event.detail.duration)
16. }
17. const onProgress = (event: UniVideoProgressEvent) => {
18.   buffered.value = event.detail.buffered
19. }
20. </script>

复制代码

5. 全屏状态与方向
@fullscreenchange 可监听全屏状态，并从事件中读取 fullScreen 和 direction。direction 只在全屏时生效：0 是竖屏，90 是横屏（逆时针），-90 是反向横屏。

2. <video src='' style='width: 100%; height: 250px;' @fullscreenchange='onFullscreenChange'></video>
3. <script setup lang='uts'>
4. const isFullscreen = ref(false)
5. const onFullscreenChange = (event: UniVideoFullScreenChangeEvent) => {
6.   isFullscreen.value = event.detail.fullScreen
7.   console.log('全屏方向:', event.detail.direction)
8. }
9. </script>

复制代码

6. 错误处理
@error 可处理播放错误，事件中有 errMsg 和 errCode。错误码包括 100001 网络错误、200001 内部错误、300001 SDK 错误。播放成功后可清除错误提示。

2. <video :src='videoUrl' style='width: 100%; height: 250px;' @error='onError' @play='onPlay'></video>
3. <script setup lang='uts'>
4. const videoUrl = ref('https://example.com/invalid-video.mp4')
5. const errorMsg = ref('')
6. const onError = (event: UniVideoErrorEvent) => {
7.   errorMsg.value = '播放失败：' + event.detail.errMsg
8.   console.log('错误码:', event.detail.errCode)
9. }
10. const onPlay = () => { errorMsg.value = '' }
11. </script>

复制代码

三、鸿蒙平台专属特性

鸿蒙平台从 HarmonyOS 4.61 开始支持 video 组件，底层使用 ArkUI 的 Video 组件。对比鸿蒙原生开发，uni-app x 的 video 属性更丰富，弹幕、小窗、投屏等功能原生往往需要自行实现。

小窗播放（画中画）可通过 picture-in-picture-mode 设置：

2. <video src='' :picture-in-picture-mode="['push', 'pop']" style='width: 100%; height: 250px;'></video>

复制代码

在 list-view 中使用 video 时，video 会被复用，可用 @recycle 和 @reuse 事件控制复用行为：

2. <list-view @scrolltolower='onLoadMore'>
3.   <list-item v-for='(item, index) in list' :key='index'>
4.     <video :src='item.src' :controls='true' @recycle='onRecycle(index)' @reuse='onReuse(index)' style='width: 100%; height: 250px;'></video>
5.   </list-item>
6. </list-view>

复制代码

鸿蒙原生 Video 组件的写法可作对照：

2. Video({ src: '', currentProgress: 0 })
3.   .width('100%')
4.   .height(250)
5.   .autoPlay(false)
6.   .controls(true)
7.   .objectFit(ImageFit.Contain)
8.   .onStart(() => {
9.     console.log('开始播放')
10.   })

复制代码

四、踩坑与修复清单

1. autoplay 需要 muted：带声音自动播放通常会被平台限制，必须同时设置 muted=true。
2. 本地视频只能访问 /static 目录：与 image 一样，本地视频要放在 /static 下。
3. poster 需要网络地址：不支持本地路径；如需本地封面，可先用 image 组件覆盖在 video 上。
4. controls=false 时 poster 无效：需要自己实现封面逻辑。
5. timeupdate 触发频率为 250ms：事件处理函数里不要做复杂操作。
6. direction 只控制全屏方向：0 竖屏，90 横屏（逆时针），-90 反向横屏。
7. HBuilderX 5.08 以后，Android 使用 ExoPlayer，iOS 使用 AVPlayer，不再支持 codec、play-strategy 属性，也不再支持 rtmp/rtsp 流媒体。

五、结论

video 组件是 uni-app x 在鸿蒙平台播放视频的标准方案。落地时先抓住几个关键点：autoplay 配合 muted；本地视频放 /static；poster 只支持网络地址；controls=false 时 poster 无效；object-fit 控制缩放；HarmonyOS 4.61 起支持；5.08 版本底层实现有变化。属性虽多，常用组合并不复杂，先把 src、controls、poster、muted 用好，再按业务加全屏、进度、小窗和错误处理。