鸿蒙开发中视频播放Video组件使用

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

以下是鸿蒙开发中Video组件的详细使用，涵盖核心API、常用方法、属性配置及示例代码，综合最新文档（截至2025年5月）整理：

一、Video组件基础

1. 组件定义与功能

• 作用：用于播放视频文件并控制播放状态，支持本地/网络视频、倍速播放、预览图等功能 。
• API版本：从API Version 4开始支持，部分特性需更高版本（如倍速控制需API 8+）。
• 权限要求：

// module.json5中申请网络权限
"requestPermissions": [{
  "name": "ohos.permission.INTERNET",
  "reason": "加载网络视频"
}]

2. 创建Video组件

Video({
  src: string | Resource,                // 视频源路径
  currentProgressRate?: number | string, // 播放倍速（API 8+）
  previewUri?: string | PixelMap,       // 预览图
  controller?: VideoController          // 控制器
})

示例：

@Entry
@Component
struct VideoPlayer {
  private controller: VideoController = new VideoController();
  @State videoSrc: Resource = $rawfile('video.mp4'); // 本地资源
  @State previewImg: Resource = $r('app.media.poster');

  build() {
    Column() {
      Video({
        src: this.videoSrc,
        previewUri: this.previewImg,
        controller: this.controller
      })
    }
  }
}

二、核心API与属性

1. 视频源类型

类型	示例代码	说明
本地资源	$rawfile('video.mp4')	需放在resources/rawfile目录
网络资源	'https://example.com/video.mp4'	需网络权限
沙箱路径	'file:///data/storage/files/video.mp4'	需文件读写权限
Data Ability	'dataability://com.example.provider/video'	需配置Data Ability

2. 常用属性

属性名	类型	默认值	说明
muted	boolean	false	是否静音播放
autoPlay	boolean	false	是否自动播放（注意：预览器无效，需在模拟器测试）
controls	boolean	true	是否显示默认控制栏（设为false可自定义UI）
objectFit	ImageFit	Cover	视频缩放模式（Contain/Cover/Fill等）
loop	boolean	false	是否循环播放

3. VideoController控制器

方法	参数	说明
start()	-	开始播放
pause()	-	暂停播放
stop()	-	停止播放（重置进度）
setCurrentTime()	time: number (秒)	跳转到指定时间
requestFullscreen()	isFullscreen: boolean	切换全屏模式

示例：

// 控制视频跳转到10秒位置
this.controller.setCurrentTime(10, SeekMode.Accurate); // API 12+支持精准跳转

三、事件监听

事件名	回调参数	说明
onStart	-	播放开始时触发
onPause	-	暂停时触发
onFinish	-	播放完成时触发
onError	-	播放失败时触发（如格式不支持）
onPrepared	{ duration: number }	视频准备完成，返回总时长（秒）
onUpdate	{ time: number }	播放进度变化时触发（可用于自定义进度条）
onFullscreenChange	{ fullscreen: boolean }	全屏状态切换时触发

示例：

Video({ /*...*/ })
  .onPrepared((event) => {
    console.log(`视频时长：${event.duration}秒`);
  })
  .onUpdate((event) => {
    this.currentTime = event.time; // 更新当前播放时间
  })

四、进阶功能

1. 自定义控制栏

通过隐藏默认控制栏（controls(false)），结合Slider和Button组件实现：

@Component
struct CustomControls {
  @Link isPlaying: boolean;
  @Link currentTime: number;
  @Link duration: number;
  private controller: VideoController;

  build() {
    Row() {
      Button(this.isPlaying ? '暂停' : '播放')
        .onClick(() => {
          this.isPlaying ? this.controller.pause() : this.controller.start();
          this.isPlaying = !this.isPlaying;
        })
      Slider({
        value: this.currentTime,
        max: this.duration
      }).onChange((value) => {
        this.controller.setCurrentTime(value);
      })
    }
  }
}

2. 多实例协同播放

使用AVPlayer（Native API）实现复杂场景（如画中画、后台播放）：

import media from '@ohos.multimedia.media';
const avPlayer = media.createAVPlayer();
avPlayer.url = 'https://example.com/video.mp4';
avPlayer.surfaceId = xComponentController.getXComponentSurfaceId(); // 绑定渲染表面
avPlayer.play();

五、注意事项

1. 格式支持：

   • 主流格式：MP4、MKV、WebM、TS
   • 不支持FLV、RMVB等特殊格式 

2. 调试限制：

   • 网络视频需在真机或模拟器测试，预览器无效 
   • 全屏模式依赖设备系统实现

3. 性能优化：

   • 大视频建议分片加载（通过AVPlayer的bufferingUpdate事件监控） 
   • 避免频繁创建/销毁Video实例，复用控制器 

4. 兼容性：

   • PlaybackSpeed倍速枚举值需API 8+支持（如1.75倍速）
   • SeekMode精准跳转需API 12+

 六、完整示例

@Entry
@Component
struct FullVideoDemo {
  private controller: VideoController = new VideoController();
  @State src: string = 'https://example.com/video.mp4';
  @State isPlaying: boolean = false;
  @State currentTime: number = 0;

  build() {
    Column() {
      Video({
        src: this.src,
        controller: this.controller
      })
        .controls(false)
        .autoPlay(false)
        .onStart(() => this.isPlaying = true)
        .onPause(() => this.isPlaying = false)
        .onPrepared((event) => console.log(`准备完成，时长：${event.duration}s`))
        .onUpdate((event) => this.currentTime = event.time)

      // 自定义控制栏
      Row() {
        Button(this.isPlaying ? '暂停' : '播放').onClick(() => {
          this.controller[this.isPlaying ? 'pause' : 'start']();
        })
        Text(`${this.currentTime.toFixed(1)}s`)
      }
    }
  }
}