鸿蒙5.0开发进阶：UI框架-ArkTS组件（Video）

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了
  
• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线
  
• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
  
• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）
  

---

Video

用于播放视频文件并控制其播放状态的组件。
   阐明
  该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
  Video组件只提供简单的视频播放功能，无法支撑复杂的视频播控场景。复杂开发场景保举使用AVPlayer播控API和XComponent组件开发。
  权限列表

使用网络视频时，必要申请权限ohos.permission.INTERNET。
子组件

不支持子组件。
接口

Video

Video(value: VideoOptions)
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueVideoOptions是视频信息。 VideoOptions对象阐明

元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
名称类型必填阐明srcstring | Resource否 视频的数据源，支持本地视频和网络视频。
Resource格式可以跨包/跨模块访问资源文件，常用于访问本地视频。
- 支持rawfile文件下的资源，即通过$rawfile引用视频文件。
string格式可用于加载网络视频和本地视频，常用于加载网络视频。
- 支持网络视频地点。
- 支持file://路径前缀的字符串，即应用沙箱URI：file://<bundleName>/<sandboxPath>。用于读取应用沙箱路径内的资源。必要保证目录包路径下的文件有可读权限。
阐明：
视频支持的格式是：mp4、mkv、TS。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
currentProgressRatenumber | string | PlaybackSpeed8+否 视频播放倍速。
阐明：
number取值仅支持：0.75，1.0，1.25，1.75，2.0。
默认值：1.0 | PlaybackSpeed.Speed_Forward_1_00_X
元服务API： 从API version 11开始，该接口支持在元服务中使用。
previewUristring | PixelMap | Resource否 视频未播放时的预览图片路径，默认不表现图片。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
controllerVideoController否 设置视频控制器，可以控制视频的播放状态。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
imageAIOptions12+ImageAIOptions否 设置图像AI分析选项，可设置分析类型或绑定一个分析控制器。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
  PlaybackSpeed8+枚举阐明

元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
名称描述Speed_Forward_0_75_X0.75倍速播放。Speed_Forward_1_00_X1倍速播放。Speed_Forward_1_25_X1.25倍速播放。Speed_Forward_1_75_X1.75倍速播放。Speed_Forward_2_00_X2倍速播放。 属性

除支持通用属性外，还支持以部属性：
muted

muted(value: boolean)
设置是否静音。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueboolean是 是否静音。
默认值：false
  autoPlay

autoPlay(value: boolean)
设置是否自动播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueboolean是 是否自动播放。
默认值：false
  controls

controls(value: boolean)
设置控制视频播放的控制栏是否表现。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueboolean是 控制视频播放的控制栏是否表现。
默认值：true
  objectFit

objectFit(value: ImageFit)
设置视频表现模式。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueImageFit是 视频表现模式。
默认值：Cover
  loop

loop(value: boolean)
设置是否单个视频循环播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueboolean是 是否单个视频循环播放。
默认值：false
  enableAnalyzer12+

enableAnalyzer(enable: boolean)
设置组件支持AI分析，当前支持主体识别、笔墨识别和对象查找等功能。
使能后，视频播放暂停时自动进入分析状态，开始分析当前画面帧，视频继续播放后自动退出分析状态。
不能和overlay属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明enableboolean是是否启用AI分析功能   阐明
  当前仅在使用自定义控制栏(controls属性设置为false)时支持该功能。
  该特性依靠设备能力。
  analyzerConfig12+

analyzerConfig(config: ImageAnalyzerConfig)
设置AI分析识别类型，包括主体识别、笔墨识别和对象查找等功能。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数名类型必填阐明configImageAnalyzerConfig是设置AI分析识别类型 事件

除支持通用事件外，还支持以下事件：
onStart

onStart(event) => void)
播放时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
onPause

onPause(event) => void)
暂停时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
onFinish

onFinish(event) => void)
播放结束时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
onError

onError(event) => void)
播放失败时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
onStop12+

onStop(event: Callback<void>)
播放停止时触发该事件(当stop()方法被调用后触发)。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
onPrepared

onPrepared(callbackevent: { duration: number }) => void)
视频准备完成时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明durationnumber是当前视频的时长，单位为秒。 onSeeking

onSeeking(callbackevent: { time: number }) => void)
操作进度条过程时上报时间信息。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明timenumber是当前视频播放的进度，单位为秒。 onSeeked

onSeeked(callbackevent: { time: number }) => void)
操作进度条完成后，上报播放时间信息。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明timenumber是当前视频播放的进度，单位为秒。 onUpdate

onUpdate(callbackevent: { time: number }) => void)
播放进度变革时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明timenumber是当前视频播放的进度，单位为秒。 onFullscreenChange

onFullscreenChange(callbackevent: { fullscreen: boolean }) => void)
在全屏播放与非全屏播放状态之间切换时触发该事件。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明fullscreenboolean是为true表现进入全屏播放状态，为false则表现非全屏播放。 VideoController

一个VideoController对象可以控制一个或多个video，可用视频播放实例请参考@ohos.multimedia.media。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
导入对象

1. let controller: VideoController = new VideoController()

复制代码

constructor

constructor()
VideoController的构造函数。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
start

start()
开始播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
pause

pause()
暂停播放，表现当前帧，再次播放时从当前位置继续播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
stop

stop()
停止播放，表现当前帧，再次播放时从头开始播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
reset12+

reset(): void
video组件重置AVPlayer。表现当前帧，再次播放时从头开始播放。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
setCurrentTime

setCurrentTime(value: number)
指定视频播放的进度位置。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuenumber是视频播放进度位置，单位为s。 requestFullscreen

requestFullscreen(value: boolean)
请求全屏播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueboolean是是否全屏（添补满应用窗口）播放。 exitFullscreen

exitFullscreen()
退出全屏播放。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
setCurrentTime8+

setCurrentTime(value: number, seekMode: SeekMode)
指定视频播放的进度位置，并指定跳转模式。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuenumber是视频播放进度位置，单位为s。seekModeSeekMode是跳转模式。 SeekMode8+枚举阐明

元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系能力： SystemCapability.ArkUI.ArkUI.Full
名称描述PreviousKeyframe跳转到前一个最近的关键帧。NextKeyframe跳转到后一个最近的关键帧。ClosestKeyframe跳转到最近的关键帧。Accurate精准跳转，岂论是否为关键帧。 示例

示例1（视频播放底子用法）

底子用法，包括控制栏、预览图、自动播放、播放速率、控制器（开始播放、暂停播放、停止播放、重置avPlayer、跳转等）以及一些状态回调方法。

1. // xxx.ets
2. @Entry
3. @Component
4. struct VideoCreateComponent {
5.   @State videoSrc: Resource = $rawfile('video1.mp4')
6.   @State previewUri: Resource = $r('app.media.poster1')
7.   @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X
8.   @State isAutoPlay: boolean = false
9.   @State showControls: boolean = true
10.   controller: VideoController = new VideoController()
12.   build() {
13.     Column() {
14.       Video({
15.         src: this.videoSrc,
16.         previewUri: this.previewUri,
17.         currentProgressRate: this.curRate,
18.         controller: this.controller
19.       })
20.         .width('100%')
21.         .height(600)
22.         .autoPlay(this.isAutoPlay)
23.         .controls(this.showControls)
24.         .onStart(() => {
25.           console.info('onStart')
26.         })
27.         .onPause(() => {
28.           console.info('onPause')
29.         })
30.         .onFinish(() => {
31.           console.info('onFinish')
32.         })
33.         .onError(() => {
34.           console.info('onError')
35.         })
36.         .onStop(() => {
37.           console.info('onStop')
38.         })
39.         .onPrepared((e?: DurationObject) => {
40.           if (e != undefined) {
41.             console.info('onPrepared is ' + e.duration)
42.           }
43.         })
44.         .onSeeking((e?: TimeObject) => {
45.           if (e != undefined) {
46.             console.info('onSeeking is ' + e.time)
47.           }
48.         })
49.         .onSeeked((e?: TimeObject) => {
50.           if (e != undefined) {
51.             console.info('onSeeked is ' + e.time)
52.           }
53.         })
54.         .onUpdate((e?: TimeObject) => {
55.           if (e != undefined) {
56.             console.info('onUpdate is ' + e.time)
57.           }
58.         })
60.       Row() {
61.         Button('src').onClick(() => {
62.           this.videoSrc = $rawfile('video2.mp4') // 切换视频源
63.         }).margin(5)
64.         Button('previewUri').onClick(() => {
65.           this.previewUri = $r('app.media.poster2') // 切换视频预览海报
66.         }).margin(5)
67.         Button('controls').onClick(() => {
68.           this.showControls = !this.showControls // 切换是否显示视频控制栏
69.         }).margin(5)
70.       }
72.       Row() {
73.         Button('start').onClick(() => {
74.           this.controller.start() // 开始播放
75.         }).margin(2)
76.         Button('pause').onClick(() => {
77.           this.controller.pause() // 暂停播放
78.         }).margin(2)
79.         Button('stop').onClick(() => {
80.           this.controller.stop() // 结束播放
81.         }).margin(2)
82.         Button('reset').onClick(() => {
83.           this.controller.reset() // 重置AVPlayer
84.         }).margin(2)
85.         Button('setTime').onClick(() => {
86.           this.controller.setCurrentTime(10, SeekMode.Accurate) // 精准跳转到视频的10s位置
87.         }).margin(2)
88.       }
90.       Row() {
91.         Button('rate 0.75').onClick(() => {
92.           this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // 0.75倍速播放
93.         }).margin(5)
94.         Button('rate 1').onClick(() => {
95.           this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // 原倍速播放
96.         }).margin(5)
97.         Button('rate 2').onClick(() => {
98.           this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // 2倍速播放
99.         }).margin(5)
100.       }
101.     }
102.   }
103. }
105. interface DurationObject {
106.   duration: number;
107. }
109. interface TimeObject {
110.   time: number;
111. }

复制代码

示例2（图像分析功能）

使用enableAnalyzer属性开启图像AI分析。

1. // xxx.ets
2. @Entry
3. @Component
4. struct ImageAnalyzerExample {
5.   @State videoSrc: Resource = $rawfile('video1.mp4')
6.   @State previewUri: Resource = $r('app.media.poster1')
7.   @State showControls: boolean = true
8.   controller: VideoController = new VideoController()
9.   config: ImageAnalyzerConfig = {
10.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
11.   }
12.   private aiController: ImageAnalyzerController = new ImageAnalyzerController()
13.   private options: ImageAIOptions = {
14.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
15.     aiController: this.aiController
16.   }
18.   build() {
19.     Column() {
20.       Video({
21.         src: this.videoSrc,
22.         previewUri: this.previewUri,
23.         controller: this.controller,
24.         imageAIOptions: this.options
25.       })
26.         .width('100%')
27.         .height(600)
28.         .controls(false)
29.         .enableAnalyzer(true)
30.         .analyzerConfig(this.config)
31.         .onStart(() => {
32.           console.info('onStart')
33.         })
34.         .onPause(() => {
35.           console.info('onPause')
36.         })
38.       Row() {
39.         Button('start').onClick(() => {
40.           this.controller.start() // 开始播放
41.         }).margin(5)
42.         Button('pause').onClick(() => {
43.           this.controller.pause() // 暂停播放
44.         }).margin(5)
45.         Button('getTypes').onClick(() => {
46.             this.aiController.getImageAnalyzerSupportTypes()
47.         }).margin(5)
48.       }
49.     }
50.   }
51. }

复制代码

示例3（播放拖入的视频）

以下示例展示了怎样使Video组件可以或许播放拖入的视频。

1. import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData';
3. @Entry
4. @Component
5. struct Index {
6.   @State videoSrc: Resource | string = $rawfile('video1.mp4');
7.   private controller: VideoController = new VideoController();
9.   build() {
10.     Column() {
11.       Video({
12.         src: this.videoSrc,
13.         controller: this.controller
14.       })
15.         .width('100%')
16.         .height(600)
17.         .onPrepared(() => {
18.           // 在onPrepared回调中执行controller的start方法，确保视频源更换后直接开始播放。
19.           this.controller.start();
20.         })
21.         .onDrop((e: DragEvent) => {
22.           // 外部视频拖入应用Video组件范围，松手后触发通过onDrop注册的回调。
23.           // 在DragEvent中会包含拖入的视频源信息，取出后赋值给状态变量videoSrc即可改变Video的视频源。
24.           let record = e.getData().getRecords()[0];
25.           if (record.getType() == uniformTypeDescriptor.UniformDataType.VIDEO) {
26.             let videoInfo = record as unifiedDataChannel.Video;
27.             this.videoSrc = videoInfo.videoUri;
28.           }
29.         })
30.     }
31.   }
32. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。