网站导航
> 技术文档 > 手把手教你玩转 HarmonyOS 的 Video 视频播放组件_harmonyos播放视频

手把手教你玩转 HarmonyOS 的 Video 视频播放组件_harmonyos播放视频

网友: 技术文档 2025-09-03 23:33:07

今天咱们来聊聊 HarmonyOS 里的 Video 组件，这可是实现视频播放功能的核心组件。不管是做短视频 APP、在线教育应用还是企业内部培训系统，视频播放都是必不可少的功能。Video 组件从 API version 7 就开始支持了，经过多个版本的迭代，现在功能已经相当完善。接下来我会用最接地气的话，带大家把这个组件的每个知识点都吃透，还会配上实实在在的代码示例，让你一看就懂、一学就会。

一、Video 组件基础用法：快速实现视频播放

Video 组件的核心功能就是播放视频文件并控制其播放状态。使用起来也很简单，咱们先来看一个最基础的视频播放示例：

@Entry@Componentstruct BasicVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State previewUri: Resource = $r(\'app.media.poster1\') build() { Column { Video({ src: this.videoSrc, previewUri: this.previewUri }) .width(\'100%\') .height(400) .autoPlay(true) .controls(true) } .padding(10) }}

这段代码实现了一个基础的视频播放界面，主要做了以下几件事：

  • 通过src属性指定视频源，这里用了本地资源$rawfile(\'video1.mp4\')
  • 通过previewUri设置视频未播放时的预览图
  • 设置视频宽度为 100%，高度 400，适应屏幕
  • 开启autoPlay自动播放
  • 显示controls控制栏，方便用户操作

需要注意的是，视频支持的格式是 mp4、mkv、TS，如果你要播放其他格式的视频可能需要先转码。另外，如果是网络视频，需要在配置文件中申请ohos.permission.INTERNET权限。

二、核心属性详解：定制你的视频播放界面

Video 组件有很多实用的属性，通过设置这些属性，咱们可以全方位定制视频播放的外观和行为。

1. muted：控制视频静音

这个属性用来设置视频是否静音，就像手机的静音键一样，非常实用。比如在浏览短视频时，默认静音播放可以避免突然出声打扰用户。

@Entry@Componentstruct MutedVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State isMuted: boolean = true build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .muted(this.isMuted) .controls(true) Button(`静音状态: ${this.isMuted ? \'开启\' : \'关闭\'}`) .onClick(() => { this.isMuted = !this.isMuted }) .margin(10) } .padding(10) }}

2. autoPlay：设置自动播放

autoPlay属性可以控制视频是否自动播放。在一些场景下，比如广告视频，我们希望视频一进入页面就自动播放；而在另一些场景下，比如用户列表页，可能需要点击后再播放。

@Entry@Componentstruct AutoPlayVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State isAutoPlay: boolean = false build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .autoPlay(this.isAutoPlay) .controls(true) Button(`自动播放: ${this.isAutoPlay ? \'开启\' : \'关闭\'}`) .onClick(() => { this.isAutoPlay = !this.isAutoPlay }) .margin(10) } .padding(10) }}

3. controls：显示 / 隐藏控制栏

控制栏包含了播放按钮、进度条、音量控制等控件，controls属性可以控制它是否显示。如果需要自定义控制栏，就可以先隐藏默认控制栏，然后自己实现。

@Entry@Componentstruct ControlsVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State showControls: boolean = true build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .controls(this.showControls) Button(`显示控制栏: ${this.showControls ? \'是\' : \'否\'}`) .onClick(() => { this.showControls = !this.showControls }) .margin(10) } .padding(10) }}

4. objectFit：设置视频显示模式

objectFit属性可以控制视频在容器中的显示方式，类似于图片的缩放模式。比如想要视频铺满容器可以用Cover，想要保持原始比例可以用Contain。

@Entry@Componentstruct ObjectFitVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State fitMode: ImageFit = ImageFit.Cover build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .objectFit(this.fitMode) .controls(true) Row { Button(\'Cover\') .onClick(() => { this.fitMode = ImageFit.Cover }) .margin(5) Button(\'Contain\') .onClick(() => { this.fitMode = ImageFit.Contain }) .margin(5) Button(\'Fill\') .onClick(() => { this.fitMode = ImageFit.Fill }) .margin(5) } } .padding(10) }}

5. loop：设置循环播放

loop属性可以让视频播放完后自动重新开始，适合用于广告轮播、背景视频等场景。

@Entry@Componentstruct LoopVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State isLoop: boolean = false build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .loop(this.isLoop) .controls(true) Button(`循环播放: ${this.isLoop ? \'开启\' : \'关闭\'}`) .onClick(() => { this.isLoop = !this.isLoop }) .margin(10) } .padding(10) }}

三、VideoController：更灵活的视频控制

除了通过属性控制视频播放，我们还可以使用VideoController来更灵活地控制视频状态。VideoController就像一个万能遥控器，可以独立控制视频的播放、暂停、跳转等操作。

@Entry@Componentstruct VideoControllerDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') controller: VideoController = new VideoController() build() { Column { Video({ src: this.videoSrc, controller: this.controller }) .width(\'100%\') .height(400) .controls(true) Row { Button(\'开始播放\') .onClick(() => { this.controller.start() }) .margin(5) Button(\'暂停播放\') .onClick(() => { this.controller.pause() }) .margin(5) Button(\'停止播放\') .onClick(() => { this.controller.stop() }) .margin(5) } Button(\'跳转到30秒\') .onClick(() => { this.controller.setCurrentTime(30) }) .margin(10) } .padding(10) }}

上面的代码中，我们创建了一个VideoController实例，并将其关联到 Video 组件。通过控制器，我们可以：

  • start()：开始播放视频
  • pause()：暂停播放
  • stop()：停止播放，再次播放时从头开始
  • setCurrentTime(30)：跳转到 30 秒的位置

带跳转模式的精准控制

从 API version 8 开始，setCurrentTime支持指定跳转模式，比如跳转到最近的关键帧或者精准跳转。这在需要快速定位视频内容时非常有用。

@Entry@Componentstruct SeekModeVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') controller: VideoController = new VideoController() build() { Column { Video({ src: this.videoSrc, controller: this.controller }) .width(\'100%\') .height(400) .controls(true) Row { Button(\'精准跳转(Accurate)\') .onClick(() => { this.controller.setCurrentTime(20, SeekMode.Accurate) }) .margin(5) Button(\'最近关键帧(ClosestKeyframe)\') .onClick(() => { this.controller.setCurrentTime(20, SeekMode.ClosestKeyframe) }) .margin(5) } Row { Button(\'前一个关键帧(PreviousKeyframe)\') .onClick(() => { this.controller.setCurrentTime(20, SeekMode.PreviousKeyframe) }) .margin(5) Button(\'后一个关键帧(NextKeyframe)\') .onClick(() => { this.controller.setCurrentTime(20, SeekMode.NextKeyframe) }) .margin(5) } } .padding(10) }}

四、播放倍速控制：快慢播放随心所欲

从 API version 8 开始，Video 组件支持播放倍速控制，用户可以根据需要选择 0.75 倍到 2 倍的播放速度，这在学习视频、观看长视频时非常实用。

@Entry@Componentstruct PlaybackSpeedDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X build() { Column { Video({ src: this.videoSrc, currentProgressRate: this.curRate }) .width(\'100%\') .height(400) .controls(true) Row { Button(\'0.75倍速\') .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_0_75_X }) .margin(5) Button(\'1.0倍速\') .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_1_00_X }) .margin(5) Button(\'1.25倍速\') .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_1_25_X }) .margin(5) } Row { Button(\'1.75倍速\') .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_1_75_X }) .margin(5) Button(\'2.0倍速\') .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_2_00_X }) .margin(5) } } .padding(10) }}

五、事件监听：掌握视频播放状态

Video 组件提供了丰富的事件监听，我们可以通过这些事件了解视频的播放状态，比如开始播放、暂停、播放结束等，从而做出相应的处理。

@Entry@Componentstruct VideoEventsDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State status: string = \'等待播放\' build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .controls(true) .onStart(() => { this.status = \'开始播放\' console.info(\'视频开始播放\') }) .onPause(() => { this.status = \'已暂停\' console.info(\'视频暂停\') }) .onFinish(() => { this.status = \'播放结束\' console.info(\'视频播放结束\') }) .onError(() => { this.status = \'播放错误\' console.info(\'视频播放错误\') }) .onPrepared((e) => { this.status = `准备完成，视频时长: ${e.duration}秒` console.info(`视频准备完成，时长: ${e.duration}秒`) }) Text(`当前状态: ${this.status}`) .margin(10) .fontSize(16) } .padding(10) }}

上面的代码中，我们监听了多个事件：

  • onStart：开始播放时触发
  • onPause：暂停时触发
  • onFinish：播放结束时触发
  • onError：播放错误时触发
  • onPrepared：视频准备完成时触发，返回视频时长

六、全屏播放控制：沉浸式观看体验

视频全屏播放是一个很重要的功能，Video 组件提供了便捷的全屏控制方法，可以轻松实现全屏和退出全屏。

@Entry@Componentstruct FullscreenVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State isFullscreen: boolean = false controller: VideoController = new VideoController() build() { Column { Video({ src: this.videoSrc, controller: this.controller }) .width(\'100%\') .height(this.isFullscreen ? \'100%\' : 400) .controls(true) .onFullscreenChange((e) => { this.isFullscreen = e.fullscreen console.info(`全屏状态: ${e.fullscreen}`) }) Button(`切换全屏: ${this.isFullscreen ? \'退出\' : \'进入\'}`) .onClick(() => { this.isFullscreen = !this.isFullscreen this.controller.requestFullscreen(this.isFullscreen) }) .margin(10) } .padding(10) }}

七、图像 AI 分析：从视频中提取信息

从 API version 12 开始，Video 组件新增了图像 AI 分析功能，支持主体识别、文字识别和对象查找等。这在视频内容分析、智能剪辑等场景下非常有用。

@Entry@Componentstruct ImageAnalysisDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') controller: VideoController = new VideoController() private aiController: ImageAnalyzerController = new ImageAnalyzerController() private options: ImageAIOptions = { types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], aiController: this.aiController } build() { Column { Video({ src: this.videoSrc, controller: this.controller, imageAIOptions: this.options }) .width(\'100%\') .height(400) .controls(false) .enableAnalyzer(true) .analyzerConfig({ types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] }) .onPause(() => { console.info(\'视频暂停，开始AI分析\') // 暂停时自动开始分析当前帧 }) Row { Button(\'开始播放\') .onClick(() => { this.controller.start() }) .margin(5) Button(\'暂停播放\') .onClick(() => { this.controller.pause() }) .margin(5) Button(\'获取支持的分析类型\') .onClick(() => { this.aiController.getImageAnalyzerSupportTypes() }) .margin(5) } } .padding(10) }}

上面的代码中，我们启用了 AI 分析功能，并设置了分析类型为主体识别和文字识别。当视频暂停时，会自动分析当前帧的内容，开发者可以根据分析结果做进一步处理。

八、快捷键支持：键盘控制更便捷

从 API version 15 开始，Video 组件支持快捷键响应，这在 TV、车载等需要键盘操作的场景下非常实用。目前支持的快捷键包括：

  • 空格键：播放 / 暂停
  • 上下方向键：调整音量
  • 左右方向键：快进 / 快退
@Entry@Componentstruct ShortcutKeyVideoDemo { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State isShortcutEnabled: boolean = false build() { Column { Video({ src: this.videoSrc }) .width(\'100%\') .height(400) .controls(true) .enableShortcutKey(this.isShortcutEnabled) Button(`快捷键支持: ${this.isShortcutEnabled ? \'开启\' : \'关闭\'}`) .onClick(() => { this.isShortcutEnabled = !this.isShortcutEnabled }) .margin(10) Text(\'使用说明:\') .fontSize(16) .fontWeight(FontWeight.Medium) .margin({ top: 10, bottom: 5 }) Text(\'- 空格键: 播放/暂停\') .fontSize(14) .margin(2) Text(\'- 上下方向键: 调整音量\') .fontSize(14) .margin(2) Text(\'- 左右方向键: 快进/快退(5秒)\') .fontSize(14) .margin(2) } .padding(10) }}

九、完整示例：打造一个多功能视频播放器

最后，咱们来整合前面学的知识点，做一个完整的多功能视频播放器，包含播放控制、倍速调节、全屏切换、快捷键支持等功能。

@Entry@Componentstruct AdvancedVideoPlayer { @State videoSrc: Resource = $rawfile(\'video1.mp4\') @State previewUri: Resource = $r(\'app.media.poster1\') @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X @State isAutoPlay: boolean = false @State showControls: boolean = true @State isShortcutEnabled: boolean = true @State isFullscreen: boolean = false controller: VideoController = new VideoController() build() { Column { Video({ src: this.videoSrc, previewUri: this.previewUri, currentProgressRate: this.curRate, controller: this.controller }) .width(\'100%\') .height(this.isFullscreen ? \'100%\' : 400) .autoPlay(this.isAutoPlay) .controls(this.showControls) .enableShortcutKey(this.isShortcutEnabled) .onFullscreenChange((e) => { this.isFullscreen = e.fullscreen }) .onPrepared((e) => { console.info(`视频准备完成，时长: ${e.duration}秒`) }) if (!this.isFullscreen) { // 非全屏时显示控制按钮 Column { Row { Button(\'开始播放\')  .onClick(() => { this.controller.start()  })  .margin(5) Button(\'暂停播放\')  .onClick(() => { this.controller.pause()  })  .margin(5) Button(\'停止播放\')  .onClick(() => { this.controller.stop()  })  .margin(5) } Row { Button(\'0.75倍速\')  .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_0_75_X  })  .margin(5) Button(\'1.0倍速\')  .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_1_00_X  })  .margin(5) Button(\'2.0倍速\')  .onClick(() => { this.curRate = PlaybackSpeed.Speed_Forward_2_00_X  })  .margin(5) } Row { Button(\'切换全屏\')  .onClick(() => { this.isFullscreen = !this.isFullscreen this.controller.requestFullscreen(this.isFullscreen)  })  .margin(5) Button(\'显示/隐藏控制栏\')  .onClick(() => { this.showControls = !this.showControls  })  .margin(5) Button(\'开启/关闭快捷键\')  .onClick(() => { this.isShortcutEnabled = !this.isShortcutEnabled  })  .margin(5) } } .padding(10) } } .padding(10) }}

这个示例整合了我们前面学习的所有知识点，实现了一个功能完整的视频播放器，包括：

  • 基本的播放、暂停、停止控制
  • 播放倍速调节
  • 全屏切换
  • 控制栏显示 / 隐藏
  • 快捷键支持
  • 视频准备完成事件监听

总结

Video 组件是 HarmonyOS 中实现视频播放的基础组件，虽然它主要提供简单的视频播放功能，对于复杂场景推荐使用 AVPlayer 和 XComponent，但在大多数日常应用中已经足够用了。通过今天的学习，我们了解了 Video 组件的基本用法、核心属性、事件监听、控制器使用以及高级功能如图像分析和快捷键支持。

在实际开发中，我们可以根据应用的具体需求，灵活运用这些功能，打造出符合用户体验的视频播放界面。无论是手机 APP、平板应用还是智能电视应用，Video 组件都能提供良好的视频播放支持。接下来，大家可以试着在自己的项目中使用这个组件，结合实际场景开发出更丰富的功能。

网络标签：

相关问题