Video组件是ArkUI框架中用于播放视频文件并控制其播放状态的核心组件，它为开发者提供了丰富的视频播放功能和控制接口。本文将全面介绍Video组件的功能特性、使用方法、事件处理以及高级功能，帮助开发者快速掌握视频播放功能的开发。

一、Video组件概述

Video组件是ArkUI框架中专门用于视频播放的组件，支持加载本地视频、网络视频以及沙箱路径视频，并可以通过设置属性和调用事件进行自定义控制。

1.1 核心特性

Video组件具有以下主要特性：

• 支持多种视频源：本地视频、网络视频、沙箱路径视频
• 提供完整的播放控制：播放、暂停、停止、进度控制等
• 支持视频预览图设置
• 丰富的播放事件回调
• 自定义控制器支持
• 全屏播放功能
• 支持视频分析功能（API12+）
• 快捷键响应支持（API15+）

1.2 基本用法

Video组件通过调用接口来创建，基本接口调用形式如下：

Video(value: VideoOptions) 

其中VideoOptions包含以下参数：

• src: 视频源，可以是本地资源、网络资源或沙箱路径
• previewUri: 视频预览图
• controller: 视频控制器
• currentProgressRate: 当前播放速率

二、创建Video组件

2.1 基本创建方式

创建一个基本的Video组件非常简单：

@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()

  build() {
    Column() {
      Video({ controller: this.controller })
    }
  }
} 

2.2 完整创建示例

下面是一个更完整的Video组件创建示例：

@Entry
@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  private previewUris: Resource = $r('app.media.preview')
  private innerResource: Resource = $rawfile('videoTest.mp4')

  build() {
    Column() {
      Video({ src: this.innerResource, previewUri: this.previewUris, controller: this.controller })
        .width('100%')
        .height(300)
    }
  }
} 

三、加载视频资源

Video组件支持多种视频源加载方式，包括本地视频、网络视频和沙箱路径视频。

3.1 加载本地视频

3.1.1 普通本地视频

加载本地rawfile目录下的视频文件：

@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  private innerResource: Resource = $rawfile('videoTest.mp4')

  build() {
    Column() {
      Video({ src: this.innerResource, controller: this.controller })
    }
  }
} 

3.1.2 Data Ability提供的视频

使用带有dataability://前缀的视频路径：

@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  private videoSrc: string = 'dataability://device_id/com.domainname.dataability.videodata/video/10'

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

3.2 加载沙箱路径视频

支持file://路径前缀的字符串，用于读取应用沙箱路径内的资源：

@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  private videoSrc: string = 'file:///data/storage/el2/base/haps/entry/files/show.mp4'

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

3.3 加载网络视频

加载网络视频时需要申请ohos.permission.INTERNET权限：

@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  private videoSrc: string = 'https://www.example.com/example.mp4'

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

四、Video组件属性

Video组件提供了丰富的属性来控制视频的播放行为和显示效果。

4.1 常用属性

Video({ controller: this.controller }) .muted(false) // 设置是否静音 .controls(false) // 设置是否显示默认控制条 .autoPlay(false) // 设置是否自动播放 .loop(false) // 设置是否循环播放 .objectFit(ImageFit.Contain) // 设置视频适配模式 

4.2 属性说明

属性	类型	说明	默认值
muted	boolean	是否静音	false
controls	boolean	是否显示默认控制条	true
autoPlay	boolean	是否自动播放	false
loop	boolean	是否循环播放	false
objectFit	ImageFit	视频适配模式	ImageFit.Contain

4.3 高级属性（API12+）

从API12开始，Video组件支持AI分析功能：

Video({ controller: this.controller }) .analyzerConfig({ analyzerType: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] }) 

五、Video控制器

VideoController是控制视频播放状态的核心类，提供了播放、暂停、停止、进度控制等功能。

5.1 基本控制方法

// 开始播放 
controller.start() 
// 暂停播放 
controller.pause() 
// 停止播放 
controller.stop() 
// 重置播放器（API12+） 
controller.reset() 
// 设置播放进度 // 跳转到第10秒 
controller.setCurrentTime(10) 
// 请求全屏播放 
controller.requestFullscreen(true) 
// 退出全屏 
controller.exitFullscreen() 

5.2 控制器使用示例

@Entry
@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()

  build() {
    Column() {
      Video({ controller: this.controller })
      Row() {
        Button('播放').onClick(() => {
          this.controller.start()
        })
        Button('暂停').onClick(() => {
          this.controller.pause()
        })
        Button('停止').onClick(() => {
          this.controller.stop()
        })
      }
    }
  }
} 

六、事件处理

Video组件提供了丰富的事件回调，用于监听视频播放过程中的各种状态变化。

6.1 常用事件

@Entry
@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()

  build() {
    Column() {
      Video({ controller: this.controller })
        .onStart(() => {
          console.info('视频开始播放')
        })
        .onPause(() => {
          console.info('视频暂停')
        })
        .onFinish(() => {
          console.info('视频播放结束')
        })
        .onError(() => {
          console.info('视频播放错误')
        })
        .onPrepared((e) => {
          console.info(`视频准备完成，时长：${e.duration}`)
        })
        .onSeeking((e) => {
          console.info(`正在跳转到：${e.time}`)
        })
        .onSeeked((e) => {
          console.info(`跳转完成：${e.time}`)
        })
        .onUpdate((e) => {
          console.info(`当前播放进度：${e.time}`)
        })
        .onFullscreenChange((e) => {
          console.info(`全屏状态变化：${e.fullscreen}`)
        })
      Row() {
        Button('播放').onClick(() => {
          this.controller.start()
        })
        Button('暂停').onClick(() => {
          this.controller.pause()
        })
        Button('停止').onClick(() => {
          this.controller.stop()
        })
      }
    }
  }
} 

6.2 事件类型说明

事件	说明
onStart	播放时触发
onPause	暂停时触发
onFinish	播放结束时触发
onError	播放失败时触发
onPrepared	视频准备完成时触发
onSeeking	进度跳转开始时触发
onSeeked	进度跳转完成时触发
onUpdate	播放进度变化时触发
onFullscreenChange	全屏状态变化时触发
onStop (API12+)	播放停止时触发

七、自定义视频控制界面

Video组件支持自定义控制界面，开发者可以关闭默认控制条，完全自定义控制界面。

7.1 关闭默认控制条

Video({ controller: this.controller }) .controls(false) 

7.2 自定义控制界面示例

@Entry
@Component
export struct VideoPlayer {
  private controller: VideoController = new VideoController()
  @State currentTime: number = 0
  @State duration: number = 0

  build() {
    Column() {
      Video({ controller: this.controller }).controls(false).onPrepared((e) => {
        this.duration = e.duration
      }).onUpdate((e) => {
        this.currentTime = e.time
      }) // 自定义进度
      Slider({
        value: this.currentTime,
        min: 0,
        max: this.duration,
        step: 1
      }).onChange((value) => {
        this.controller.setCurrentTime(value)
      })
      // 自定义控制按钮 
      Row() {
        Button('播放').onClick(() => {
          this.controller.start()
        })
        Button('暂停').onClick(() => {
          this.controller.pause()
        })
        Button('全屏').onClick(() => {
          this.controller.requestFullscreen(true)
        })
      }
    }
  }
} 

八、高级功能

8.1 快捷键支持（API15+）

从API15开始，Video组件支持快捷键响应：

Video({ controller: this.controller }) .enableShortcutKey(true) 

启用后支持以下快捷键：

• 空格键：播放/暂停
• 上下方向键：调整音量
• 左右方向键：快进/快退

8.2 同层渲染

Video组件支持同层渲染，可以与ArkUI其他组件无缝集成：

@Entry
@Component
export struct VideoWithOverlay {
  private controller: VideoController = new VideoController()

  build() {
    Stack() {
      Video({
        controller: this.controller
      })
      // 在视频上叠加其他组件 
      Text('视频标题').fontSize(20).fontColor(Color.White).margin(10)
    }
  }
} 

8.3 系统接口（API15+）

Video组件提供了一些系统接口，如设置surface背景色：

Video({ controller: this.controller }) .surfaceBackgroundColor(Color.Black) 

九、性能优化建议

1. 视频预加载：对于网络视频，可以在页面加载时提前创建Video组件但不自动播放，利用onPrepared事件监听准备完成状态。

2. 合理使用预览图：为视频设置预览图(previewUri)可以提升用户体验。

3. 资源释放：在页面销毁时调用controller.stop()释放资源。

4. 事件去重：对于频繁触发的事件如onUpdate，可以考虑添加节流逻辑。

5. 同层渲染优化：对于需要叠加UI的场景，使用Stack布局可以提高性能。

十、完整示例

下面是一个完整的视频播放器示例，包含自定义控制界面和全屏功能：

@Entry
@Component
export struct FullFeaturedVideoPlayer {
  private controller: VideoController = new VideoController()
  @State currentTime: number = 0
  @State duration: number = 0
  @State isPlaying: boolean = false
  @State isFullscreen: boolean = false
  private videoSrc: Resource = $rawfile('sample.mp4')
  private previewUris: Resource = $r('app.media.preview')

  build() {
    Column() {
      Video({
        src: this.videoSrc,
        previewUri: this.previewUris,
        controller: this.controller,
        currentProgressRate: PlaybackSpeed.Speed_Forward_1_00_X
      })
        .controls(false)
        .autoPlay(false)
        .loop(false)
        .objectFit(ImageFit.Contain)
        .onPrepared((e) => {
          this.duration = e.duration
        })
        .onUpdate((e) => {
          this.currentTime = e.time
        })
        .onStart(() => {
          this.isPlaying = true
        })
        .onPause(() => {
          this.isPlaying = false
        })
        .onFinish(() => {
          this.isPlaying = false
          this.currentTime = 0
        })
        .onFullscreenChange((e) => {
          this.isFullscreen = e.fullscreen
        })
        .width(this.isFullscreen ? '100%' : '80%')
        .height(this.isFullscreen ? '100%' :
          200)
      // 自定义控制界面 
      Row() {
        Button(this.isPlaying ? '暂停' : '播放').onClick(() => {
          if (this.isPlaying) {
            this.controller.pause()
          } else {
            this.controller.start()
          }
        })
        Text(`${this.formatTime(this.currentTime)}/${this.formatTime(this.duration)}`).margin(10)
        Slider({
          value: this.currentTime,
          min: 0,
          max: this.duration,
          step: 1
        }).layoutWeight(1).onChange((value) => {
          this.controller.setCurrentTime(value)
        })
        Button(this.isFullscreen ? '退出全屏' : '全屏').onClick(() => {
          if (this.isFullscreen) {
            this.controller.exitFullscreen()
          } else {
            this.controller.requestFullscreen(true)
          }
        })
      }.width('100%').padding(10)
    }.width('100%').height('100%')
  }

  private formatTime(seconds: number): string {
    const mins = Math.floor(seconds / 60)
    const secs = Math.floor(seconds % 60)
    return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`
  }
} 

总结

ArkUI的Video组件提供了强大而灵活的视频播放功能，从基本的播放控制到高级的自定义界面和同层渲染，能够满足各种视频播放场景的需求。通过合理使用VideoController和各种事件回调，开发者可以创建出功能丰富、用户体验优秀的视频播放应用。

在实际开发中，建议根据具体需求选择合适的视频加载方式，合理处理各种播放事件，并在性能敏感的场景下注意资源管理和优化。随着ArkUI框架的不断演进，Video组件也将持续增强功能并提升性能，为开发者提供更强大的视频播放能力。

----

以上