1# Video 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @sd-wu--> 5<!--Designer: @sunbees--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9用于播放视频文件并控制其播放状态的组件。 10 11> **说明：** 12> 13> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。<br/> 14> Video组件只提供简单的视频播放功能，无法支撑复杂的视频播控场景。复杂开发场景推荐使用[AVPlayer](../../apis-media-kit/arkts-apis-media-AVPlayer.md)播控API和[XComponent](ts-basic-components-xcomponent.md)组件开发。<br/> 15> Video组件在使用expandSafeArea扩展到安全区域时，组件视频显示内容区域不支持扩展。 16 17## 权限列表 18 19使用网络视频时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 20 21 22## 子组件 23 24不支持子组件。 25 26 27## 接口 28 29### Video 30 31Video(value: VideoOptions) 32 33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| -------- | -------- | -------- | -------- | 41| value | [VideoOptions](#videooptions对象说明) | 是 | 视频信息。 | 42 43## VideoOptions对象说明 44 45定义Video的具体配置参数。 46 47**系统能力：** SystemCapability.ArkUI.ArkUI.Full 48 49| 名称 | 类型 | 必填 | 说明 | 50| ------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 51| src | string \| [Resource](ts-types.md#resource) | 否 | 视频的数据源，支持本地视频和网络视频。<br>Resource格式可以跨包/跨模块访问资源文件，常用于访问本地视频。<br/>- 仅支持rawfile文件下的资源，即通过\$rawfile引用视频文件。<br/>string格式可用于加载网络视频和本地视频，常用于加载网络视频。<br/>- 支持网络视频地址。<br/>- 支持file://路径前缀的字符串，即[应用沙箱URI](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10)：file://\<bundleName>/\<sandboxPath>。用于读取应用沙箱路径内的资源。需要保证目录包路径下的文件有可读权限。<br/>默认值：空字符串<br/>异常值：按默认值处理<br/>**说明：**<br/>视频支持的格式是：mp4、mkv、TS。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 52| currentProgressRate | number \| string \| [PlaybackSpeed<sup>8+</sup>](#playbackspeed8枚举说明) | 否 | 视频播放倍速。<br/>**说明：**<br/>number格式取值仅支持：0.75，1.0，1.25，1.75，2.0。<br/>string格式支持number格式取值的字符串形式："0.75"，"1.0"，"1.25"，"1.75"，"2.0"。<br/>默认值：1.0 \| PlaybackSpeed.Speed_Forward_1_00_X<br/>异常值：按默认值处理<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| previewUri | string \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) \| [Resource](ts-types.md#resource) | 否 | 视频未播放时的预览图片路径，默认不显示图片。<br/>string格式可用于加载本地图片和网络图片，<br/>- 支持网络图片地址。<br/>- 支持相对路径引用本地图片，例如：previewUri: “common/test.jpg”。当使用相对路径引用本地图片时，不支持跨包/跨模块调用。<br/>- 支持file://路径前缀的字符串，即[应用沙箱URI](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10)：file://\<bundleName>/\<sandboxPath>。用于读取应用沙箱路径内的资源。需要保证目录包路径下的文件有可读权限。<br/>Resource格式可以跨包/跨模块访问资源文件。<br/>- 支持rawfile文件下的资源，即通过\$rawfile引用图片。<br/>- 支持通过\$r引用系统资源或者应用资源中的图片。<br/>默认值：空字符串<br/>异常值：按默认值处理<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 54| controller | [VideoController](#videocontroller) | 否 | 设置视频控制器，可以控制视频的播放状态。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 55| imageAIOptions<sup>12+</sup> | [ImageAIOptions](ts-image-common.md#imageaioptions12) | 否 | 设置图像AI分析选项，可配置分析类型或绑定一个分析控制器。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| posterOptions<sup>18+</sup> | [PosterOptions](#posteroptions18对象说明) | 否 | 设置视频播放的首帧送显选项，可以控制视频是否支持首帧送显。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 57 58## PlaybackSpeed<sup>8+</sup>枚举说明 59 60视频播放倍速选项。 61 62**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 63 64**系统能力：** SystemCapability.ArkUI.ArkUI.Full 65 66| 名称 | 说明 | 67| -------------------- | -------------- | 68| Speed_Forward_0_75_X | 0.75倍速播放。 | 69| Speed_Forward_1_00_X | 1倍速播放。 | 70| Speed_Forward_1_25_X | 1.25倍速播放。 | 71| Speed_Forward_1_75_X | 1.75倍速播放。 | 72| Speed_Forward_2_00_X | 2倍速播放。 | 73 74## 属性 75 76除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 77 78### muted 79 80muted(value: boolean) 81 82设置视频是否静音，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 83 84**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 85 86**系统能力：** SystemCapability.ArkUI.ArkUI.Full 87 88**参数：** 89 90| 参数名 | 类型 | 必填 | 说明 | 91| ------ | ------- | ---- | ---------------------------- | 92| value | boolean | 是 | 视频是否静音。<br/>true：开启静音；false：关闭静音。<br/>默认值：false | 93 94> **说明：** 95> 96> Video组件在未设置静音的情况下，起播瞬间会抢占音频焦点。若用户想设置静音播放不抢占其他音频焦点，应保证静音设置在开始播放视频之前。 97 98### autoPlay 99 100autoPlay(value: boolean) 101 102设置视频是否自动播放，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 103 104 105**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 106 107**系统能力：** SystemCapability.ArkUI.ArkUI.Full 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| ------ | ------- | ---- | -------------------------------- | 113| value | boolean | 是 | 是否自动播放。<br/>true：开启自动播放；false：关闭自动播放。<br/>默认值：false | 114 115### controls 116 117controls(value: boolean) 118 119设置控制视频播放的控制栏是否显示，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 120 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ------- | ---- | ----------------------------------------------- | 130| value | boolean | 是 | 控制视频播放的控制栏是否显示。<br/>true：控制栏显示；false：控制栏不显示。<br/>默认值：true | 131 132> **说明：** 133> 134> Video组件自带的控制器无法自定义。若有其他需求，可隐藏自带控制器并自定义控制器的样式或功能。参考<!--RP1-->[视频播放](https://gitee.com/harmonyos_samples/video-play)<!--RP1End-->。 135 136### objectFit 137 138objectFit(value: ImageFit) 139 140设置视频的填充模式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 141 142 143**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 144 145**系统能力：** SystemCapability.ArkUI.ArkUI.Full 146 147**参数：** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| ------ | ----------------------------------------- | ---- | -------------------------------- | 151| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 视频填充模式。<br/>默认值：Cover<br/>约束：不支持ImageFit类型中的枚举值MATRIX，若设置，则作用效果与Cover一致。<br/>异常值：若设置异常值undefined、null，或不在[ImageFit](ts-appendix-enums.md#imagefit)枚举范围内的值，作用效果均与Cover一致。| 152 153### loop 154 155loop(value: boolean) 156 157设置是否单个视频循环播放，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 158 159 160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | ------- | ---- | ---------------------------------------- | 168| value | boolean | 是 | 是否单个视频循环播放。<br/>true：开启循环播放；false：关闭循环播放。<br/>默认值：false | 169 170### enableAnalyzer<sup>12+</sup> 171 172enableAnalyzer(enable: boolean) 173 174设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 175使能后，视频播放暂停时自动进入分析状态，开始分析当前画面帧，视频继续播放后自动退出分析状态。 176不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时[overlay](ts-universal-attributes-overlay.md)中[CustomBuilder](ts-types.md#custombuilder8)属性将失效。 177 178**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 179 180**系统能力：** SystemCapability.ArkUI.ArkUI.Full 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| -------- | -------- | -------- | -------- | 186| enable | boolean | 是 | 是否启用AI分析功能。<br/>true：开启AI分析功能；false：关闭AI分析功能。<br/>默认值：false | 187 188> **说明：** 189> 190> 当前仅在使用自定义控制栏([controls](#controls)属性设置为false)时支持该功能。 191> 该特性依赖设备能力。 192 193### analyzerConfig<sup>12+</sup> 194 195analyzerConfig(config: ImageAnalyzerConfig) 196 197设置AI分析识别类型，包括主体识别、文字识别和对象查找等功能，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 198 199**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| -------- | -------- | -------- | -------- | 207| config | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig12) | 是 | 设置AI分析识别类型。 | 208 209### enableShortcutKey<sup>15+</sup> 210 211enableShortcutKey(enabled: boolean) 212 213设置组件支持快捷键响应，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 214 215目前支持在组件获焦后响应空格键播放/暂停、上下方向键调整视频音量、左右方向键快进/快退。 216 217**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224| ------- | ------- | ---- | -------------------------------------- | 225| enabled | boolean | 是 | 是否启用快捷键响应。<br/>true：开启快捷键响应；false：关闭快捷键响应。<br/>默认值：false | 226 227## 事件 228 229除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 230 231### onStart 232 233onStart(event: VoidCallback) 234 235播放时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 236 237**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 238 239**系统能力：** SystemCapability.ArkUI.ArkUI.Full 240 241**参数：** 242 243| 参数名 | 类型 | 必填 | 说明 | 244| ------ | --------------------------------------------- | ---- | ----------------------------------- | 245| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 视频播放的回调函数。 | 246 247### onPause 248 249onPause(event: VoidCallback) 250 251暂停时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 252 253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 254 255**系统能力：** SystemCapability.ArkUI.ArkUI.Full 256 257**参数：** 258 259| 参数名 | 类型 | 必填 | 说明 | 260| ------ | --------------------------------------------- | ---- | ----------------------------------- | 261| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 视频暂停的回调函数。 | 262 263### onFinish 264 265onFinish(event: VoidCallback) 266 267播放结束时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 268 269**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 270 271**系统能力：** SystemCapability.ArkUI.ArkUI.Full 272 273**参数：** 274 275| 参数名 | 类型 | 必填 | 说明 | 276| ------ | --------------------------------------------- | ---- | ----------------------------------- | 277| event | [VoidCallback](ts-types.md#voidcallback12) | 是 | 视频播放结束的回调函数。 | 278 279### onError 280 281onError(event: VoidCallback | ErrorCallback) 282 283播放失败时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 284 285**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 286 287**系统能力：** SystemCapability.ArkUI.ArkUI.Full 288 289**参数：** 290 291| 参数名 | 类型 | 必填 | 说明 | 292| ------ | --------------------------------------------- | ---- | ----------------------------------- | 293| event | [VoidCallback](ts-types.md#voidcallback12) \| [ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback)<sup>20+</sup> | 是 | 视频播放失败时的回调函数。其中[ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback)类型入参的回调函数用于接收异常信息，回调返回的错误码详细介绍请参见[Video组件错误码](../errorcode-video.md)和[媒体错误码](../../apis-media-kit/errorcode-media.md)。| 294 295### onStop<sup>12+</sup> 296 297onStop(event: Callback<void>) 298 299播放停止时触发该事件(当stop()方法被调用后触发)，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 300 301**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 302 303**系统能力：** SystemCapability.ArkUI.ArkUI.Full 304 305**参数：** 306 307| 参数名 | 类型 | 必填 | 说明 | 308| -------- | ------ | ---- | -------------------------- | 309| event | Callback\<void> | 是 | 视频播放停止时的回调函数。 | 310 311### onPrepared 312 313onPrepared(callback: Callback\<PreparedInfo>) 314 315视频准备完成时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 316 317**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 318 319**系统能力：** SystemCapability.ArkUI.ArkUI.Full 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| -------- | ------ | ---- | -------------------------- | 325| callback | Callback\<[PreparedInfo](#preparedinfo18对象说明)> | 是 | 当前视频的时长。 | 326 327### onSeeking 328 329onSeeking(callback: Callback\<PlaybackInfo>) 330 331操作进度条过程时上报时间信息，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 332 333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 334 335**系统能力：** SystemCapability.ArkUI.ArkUI.Full 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| ------ | ------ | ---- | ------------------------------ | 341| callback | Callback\<[PlaybackInfo](#playbackinfo18对象说明)> | 是 | 当前视频播放的进度。 | 342 343### onSeeked 344 345onSeeked(callback: Callback\<PlaybackInfo>) 346 347操作进度条完成后，上报播放时间信息，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 348 349**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 350 351**系统能力：** SystemCapability.ArkUI.ArkUI.Full 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| ------ | ------ | ---- | ------------------------------ | 357| callback | Callback\<[PlaybackInfo](#playbackinfo18对象说明)> | 是 | 当前视频播放的进度。 | 358 359### onUpdate 360 361onUpdate(callback: Callback\<PlaybackInfo>) 362 363播放进度变化时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 364 365**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 366 367**系统能力：** SystemCapability.ArkUI.ArkUI.Full 368 369**参数：** 370 371| 参数名 | 类型 | 必填 | 说明 | 372| ------ | ------ | ---- | ------------------------------ | 373| callback | Callback\<[PlaybackInfo](#playbackinfo18对象说明)> | 是 | 当前视频播放的进度。 | 374 375### onFullscreenChange 376 377onFullscreenChange(callback: Callback\<FullscreenInfo>) 378 379在全屏播放与非全屏播放状态之间切换时触发该事件，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 380 381**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 382 383**系统能力：** SystemCapability.ArkUI.ArkUI.Full 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| ---------- | ------- | ---- | ----------------------------------------------------- | 389| callback | Callback\<[FullscreenInfo](#fullscreeninfo18对象说明)> | 是 | 当前视频是否进入全屏播放状态。 | 390 391## FullscreenInfo<sup>18+</sup>对象说明 392 393用于描述当前视频是否进入全屏播放状态。 394 395> **说明：** 396> 397> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 398 399**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 400 401**系统能力：** SystemCapability.ArkUI.ArkUI.Full 402 403| 名称 | 类型 | 只读 | 可选 | 说明 | 404| ----------- | ------- | ---- | ---- | ---------------------------- | 405| fullscreen<sup>10+</sup> | boolean | 否 | 否 | 当前视频是否进入全屏播放状态。<br/>true：进入全屏播放状态；false：未进入全屏播放状态。<br/>默认值：false<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 406 407## PreparedInfo<sup>18+</sup>对象说明 408 409用于描述当前视频的时长。 410 411> **说明：** 412> 413> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 414 415**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 416 417**系统能力：** SystemCapability.ArkUI.ArkUI.Full 418 419| 名称 | 类型 | 只读 | 可选 | 说明 | 420| ----------- | ------- | ---- | ---- | ---------------------------- | 421| duration<sup>10+</sup> | number | 否 | 否 | 当前视频的时长。<br/>单位：秒<br/>取值范围：[0,+∞)<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 422 423## PlaybackInfo<sup>18+</sup>对象说明 424 425用于描述当前视频播放的进度。 426 427> **说明：** 428> 429> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 430 431**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 432 433**系统能力：** SystemCapability.ArkUI.ArkUI.Full 434 435| 名称 | 类型 | 只读 | 可选 | 说明 | 436| ----------- | ------- | ---- | ---- | ---------------------------- | 437| time<sup>10+</sup> | number | 否 | 否 | 当前视频播放的进度。<br/>单位：秒<br/>取值范围：[0,+∞)<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 438 439## PosterOptions<sup>18+</sup>对象说明 440 441用于描述当前视频是否配置首帧送显。 442 443**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 444 445**系统能力：** SystemCapability.ArkUI.ArkUI.Full 446 447| 名称 | 类型 | 只读 | 可选 | 说明 | 448| ----------- | ------- | ---- | ---- | ---------------------------- | 449| showFirstFrame | boolean | 否 | 是 | 当前视频是否配置首帧送显，当开启首帧送显时，[VideoOptions对象](#videooptions对象说明)中的previewUri字段不生效。<br/>true：开启首帧送显；false：关闭首帧送显。<br/>默认值：false | 450 451## VideoController 452 453一个VideoController对象可以控制一个或多个Video，可用视频播放实例请参考[@ohos.multimedia.media](../../apis-media-kit/arkts-apis-media.md)。 454 455**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 456 457**系统能力：** SystemCapability.ArkUI.ArkUI.Full 458 459### 导入对象 460 461```ts 462let controller: VideoController = new VideoController(); 463``` 464 465### constructor 466 467constructor() 468 469VideoController的构造函数。 470 471**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 472 473**系统能力：** SystemCapability.ArkUI.ArkUI.Full 474 475### start 476 477start() 478 479开始播放。 480 481**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 482 483**系统能力：** SystemCapability.ArkUI.ArkUI.Full 484 485### pause 486 487pause() 488 489暂停播放，显示当前帧，再次播放时从当前位置继续播放。 490 491**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 492 493**系统能力：** SystemCapability.ArkUI.ArkUI.Full 494 495### stop 496 497stop() 498 499停止播放，显示当前帧，再次播放时从头开始播放。 500 501**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 502 503**系统能力：** SystemCapability.ArkUI.ArkUI.Full 504 505### reset<sup>12+</sup> 506 507reset(): void 508 509Video组件重置AVPlayer。显示当前帧，再次播放时从头开始播放。 510 511**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 512 513**系统能力：** SystemCapability.ArkUI.ArkUI.Full 514 515### setCurrentTime 516 517setCurrentTime(value: number) 518 519指定视频播放的进度位置。 520 521> **说明：** 522> 523> 若用户需要从视频内的某一时间点开始播放，应关闭自动播放，在视频准备完成后先跳转再播放。 524 525**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 526 527**系统能力：** SystemCapability.ArkUI.ArkUI.Full 528 529**参数：** 530 531| 参数名 | 类型 | 必填 | 说明 | 532| ----- | ------ | ---- | -------------- | 533| value | number | 是 | 视频播放进度位置。<br>取值范围：[0, [duration](ts-media-components-video.md#preparedinfo18对象说明)]<br>单位：秒<br/>从API version 8开始，支持设置视频的跳转模式，详见[setCurrentTime<sup>8+</sup>](#setcurrenttime8)。| 534 535### requestFullscreen 536 537requestFullscreen(value: boolean) 538 539请求全屏播放。 540 541**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 542 543**系统能力：** SystemCapability.ArkUI.ArkUI.Full 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| ------ | -------- | ---- | -------------------------------- | 549| value | boolean | 是 | 是否全屏（填充满应用窗口）播放。<br/>true：请求全屏播放；false：不请求全屏播放。<br/>默认值：false | 550 551> **说明：** 552> 553> Video组件自带的全屏功能仅将视频内容设为全屏，显示默认控制器，无法显示自定义标题或控制器。如需其他功能，用户需自行实现全屏功能。 554 555### exitFullscreen 556 557exitFullscreen() 558 559退出全屏播放。 560 561**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 562 563**系统能力：** SystemCapability.ArkUI.ArkUI.Full 564 565### setCurrentTime<sup>8+</sup> 566 567setCurrentTime(value: number, seekMode: SeekMode) 568 569指定视频播放的进度位置，并指定跳转模式。 570 571**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 572 573**系统能力：** SystemCapability.ArkUI.ArkUI.Full 574 575**参数：** 576 577| 参数名 | 类型 | 必填 | 说明 | 578| -------- | -------- | ---- | -------------- | 579| value | number | 是 | 视频播放进度位置。<br>取值范围：[0, [duration](ts-media-components-video.md#preparedinfo18对象说明)]<br>单位：秒 | 580| seekMode | [SeekMode](#seekmode8枚举说明) | 是 | 跳转模式。 | 581 582## SeekMode<sup>8+</sup>枚举说明 583 584视频跳转模式选项。 585 586**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 587 588**系统能力：** SystemCapability.ArkUI.ArkUI.Full 589 590| 名称 | 说明 | 591| ---------------- | ---------------------------- | 592| PreviousKeyframe | 跳转到前一个最近的关键帧。 | 593| NextKeyframe | 跳转到后一个最近的关键帧。 | 594| ClosestKeyframe | 跳转到最近的关键帧。 | 595| Accurate | 精准跳转，不论是否为关键帧。 | 596 597## 示例 598 599### 示例1（视频播放基础用法） 600 601基础用法包括：控制栏、预览图、自动播放、播放速度、响应快捷键（从API version 15开始，支持通过[enableShortcutKey](#enableshortcutkey15)设置组件开启快捷键响应）、控制器（开始播放、暂停播放、停止播放、重置AVPlayer、跳转等）、首帧送显（从API version 18开始，支持通过[posterOptions](#posteroptions18对象说明)设置视频播放的首帧送显选项）以及一些状态回调方法。 602 603```ts 604// xxx.ets 605@Entry 606@Component 607struct VideoCreateComponent { 608 // $rawfile('video1.mp4')、$r('app.media.poster1')需要分别替换为开发者所需的视频、图片资源文件 609 @State videoSrc: Resource = $rawfile('video1.mp4'); 610 @State previewUri: Resource = $r('app.media.poster1'); 611 @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X; 612 @State isAutoPlay: boolean = false; 613 @State showControls: boolean = true; 614 @State isShortcutKeyEnabled: boolean = false; 615 @State showFirstFrame: boolean = false; 616 controller: VideoController = new VideoController(); 617 618 build() { 619 Column() { 620 Video({ 621 src: this.videoSrc, 622 previewUri: this.previewUri, // 设置预览图 623 currentProgressRate: this.curRate, // 设置播放速度 624 controller: this.controller, 625 posterOptions: { showFirstFrame: this.showFirstFrame } // 关闭首帧送显 626 }) 627 .width('100%') 628 .height(600) 629 .autoPlay(this.isAutoPlay) 630 .controls(this.showControls) 631 .enableShortcutKey(this.isShortcutKeyEnabled) 632 .onStart(() => { 633 console.info('onStart'); 634 }) 635 .onPause(() => { 636 console.info('onPause'); 637 }) 638 .onFinish(() => { 639 console.info('onFinish'); 640 }) 641 .onError(() => { 642 console.info('onError'); 643 }) 644 .onStop(() => { 645 console.info('onStop'); 646 }) 647 .onPrepared((e?: DurationObject) => { 648 if (e != undefined) { 649 console.info('onPrepared is ' + e.duration); 650 } 651 }) 652 .onSeeking((e?: TimeObject) => { 653 if (e != undefined) { 654 console.info('onSeeking is ' + e.time); 655 } 656 }) 657 .onSeeked((e?: TimeObject) => { 658 if (e != undefined) { 659 console.info('onSeeked is ' + e.time); 660 } 661 }) 662 .onUpdate((e?: TimeObject) => { 663 if (e != undefined) { 664 console.info('onUpdate is ' + e.time); 665 } 666 }) 667 .onFullscreenChange((e?: FullscreenObject) => { 668 if (e != undefined) { 669 console.info('onFullscreenChange is ' + e.fullscreen); 670 } 671 }) 672 673 Row() { 674 // $rawfile('video2.mp4')、$r('app.media.poster2')需要分别替换为开发者所需的视频、图片资源文件 675 Button('src').onClick(() => { 676 this.videoSrc = $rawfile('video2.mp4'); // 切换视频源。 677 }).margin(5) 678 Button('previewUri').onClick(() => { 679 this.previewUri = $r('app.media.poster2'); // 切换视频预览海报。 680 }).margin(5) 681 Button('controls').onClick(() => { 682 this.showControls = !this.showControls; // 切换是否显示视频控制栏 683 }).margin(5) 684 } 685 686 Row() { 687 Button('start').onClick(() => { 688 this.controller.start(); // 开始播放 689 }).margin(2) 690 Button('pause').onClick(() => { 691 this.controller.pause(); // 暂停播放 692 }).margin(2) 693 Button('stop').onClick(() => { 694 this.controller.stop(); // 结束播放 695 }).margin(2) 696 Button('reset').onClick(() => { 697 this.controller.reset(); // 重置AVPlayer 698 }).margin(2) 699 Button('setTime').onClick(() => { 700 this.controller.setCurrentTime(10, SeekMode.Accurate); // 精准跳转到视频的10s位置 701 }).margin(2) 702 } 703 704 Row() { 705 Button('rate 0.75').onClick(() => { 706 this.curRate = PlaybackSpeed.Speed_Forward_0_75_X; // 0.75倍速播放 707 }).margin(5) 708 Button('rate 1').onClick(() => { 709 this.curRate = PlaybackSpeed.Speed_Forward_1_00_X; // 原倍速播放 710 }).margin(5) 711 Button('rate 2').onClick(() => { 712 this.curRate = PlaybackSpeed.Speed_Forward_2_00_X; // 2倍速播放 713 }).margin(5) 714 } 715 } 716 } 717} 718 719interface DurationObject { 720 duration: number; 721} 722 723interface TimeObject { 724 time: number; 725} 726 727interface FullscreenObject { 728 fullscreen: boolean; 729} 730``` 731 732### 示例2（图像分析功能） 733 734通过enableAnalyzer属性开启图像AI分析。 735 736```ts 737// xxx.ets 738@Entry 739@Component 740struct ImageAnalyzerExample { 741 // $rawfile('video1.mp4')、$r('app.media.poster1')需要分别替换为开发者所需的视频、图片资源文件 742 @State videoSrc: Resource = $rawfile('video1.mp4'); 743 @State previewUri: Resource = $r('app.media.poster1'); 744 controller: VideoController = new VideoController(); 745 config: ImageAnalyzerConfig = { 746 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 747 } 748 private aiController: ImageAnalyzerController = new ImageAnalyzerController(); 749 private options: ImageAIOptions = { 750 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 751 aiController: this.aiController 752 } 753 754 build() { 755 Column() { 756 Video({ 757 src: this.videoSrc, 758 previewUri: this.previewUri, 759 controller: this.controller, 760 imageAIOptions: this.options // 设置图像AI分析选项 761 }) 762 .width('100%') 763 .height(600) 764 .controls(false) 765 .enableAnalyzer(true) 766 .analyzerConfig(this.config) 767 .onStart(() => { 768 console.info('onStart'); 769 }) 770 .onPause(() => { 771 console.info('onPause'); 772 }) 773 774 Row() { 775 Button('start').onClick(() => { 776 this.controller.start(); // 开始播放 777 }).margin(5) 778 Button('pause').onClick(() => { 779 this.controller.pause(); // 暂停播放 780 }).margin(5) 781 Button('getTypes').onClick(() => { 782 this.aiController.getImageAnalyzerSupportTypes(); 783 }).margin(5) 784 } 785 } 786 } 787} 788``` 789 790### 示例3（播放拖入的视频） 791 792以下示例展示了如何使Video组件能够播放拖入的视频。 793 794```ts 795// xxx.ets 796import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData'; 797 798@Entry 799@Component 800struct Index { 801 // $rawfile('video1.mp4')需要替换为开发者所需的视频资源文件 802 @State videoSrc: Resource | string = $rawfile('video1.mp4'); 803 private controller: VideoController = new VideoController(); 804 805 build() { 806 Column() { 807 Video({ 808 src: this.videoSrc, 809 controller: this.controller 810 }) 811 .width('100%') 812 .height(600) 813 .onPrepared(() => { 814 // 在onPrepared回调中执行controller的start方法，确保视频源更换后直接开始播放。 815 this.controller.start(); 816 }) 817 .onDrop((e: DragEvent) => { 818 // 外部视频拖入应用Video组件范围，松手后触发通过onDrop注册的回调。 819 // 在DragEvent中会包含拖入的视频源信息，取出后赋值给状态变量videoSrc即可改变Video的视频源。 820 let record = e.getData().getRecords()[0]; 821 if (record.getType() == uniformTypeDescriptor.UniformDataType.VIDEO) { 822 let videoInfo = record as unifiedDataChannel.Video; 823 this.videoSrc = videoInfo.videoUri; 824 } 825 }) 826 } 827 } 828} 829``` 830### 示例4（视频填充模式） 831 832通过objectFit属性设置视频填充模式。 833 834```ts 835// xxx.ets 836@Entry 837@Component 838struct VideoObject { 839 // $rawfile('rabbit.mp4')、$r('app.media.tree')需要分别替换为开发者所需的视频、图片资源文件 840 @State videoSrc: Resource = $rawfile('rabbit.mp4'); 841 @State previewUri: Resource = $r('app.media.tree'); 842 @State showControls: boolean = true; 843 controller: VideoController = new VideoController(); 844 845 build() { 846 Column() { 847 Text("ImageFit.Contain").fontSize(12) 848 Video({ 849 src: this.videoSrc, 850 previewUri: this.previewUri, 851 controller: this.controller 852 }) 853 .width(350) 854 .height(230) 855 .controls(this.showControls) 856 .objectFit(ImageFit.Contain) // 设置视频填充模式为ImageFit.Contain 857 .margin(5) 858 859 Text("ImageFit.Fill").fontSize(12) 860 Video({ 861 src: this.videoSrc, 862 previewUri: this.previewUri, 863 controller: this.controller 864 }) 865 .width(350) 866 .height(230) 867 .controls(this.showControls) 868 .objectFit(ImageFit.Fill) // 设置视频填充模式为ImageFit.Fill 869 .margin(5) 870 871 Text("ImageFit.START").fontSize(12) 872 Video({ 873 src: this.videoSrc, 874 previewUri: this.previewUri, 875 controller: this.controller 876 }) 877 .width(350) 878 .height(230) 879 .controls(this.showControls) 880 .objectFit(ImageFit.START) // 设置视频填充模式为ImageFit.START 881 .margin(5) 882 }.width('100%').alignItems(HorizontalAlign.Center) 883 } 884} 885``` 886 887 888### 示例5（onError事件上报错误码） 889 890从API version 20开始，支持通过[onError](#onerror)获取错误信息，该示例以传入不存在的视频资源路径为例。 891 892```ts 893// xxx.ets 894@Entry 895@Component 896struct VideoErrorComponent { 897 @State videoSrc: string = "video.mp4"; // 传入不存在的视频资源路径。 898 @State isAutoPlay: boolean = false; 899 @State showControls: boolean = true; 900 @State showFirstFrame: boolean = false; 901 controller: VideoController = new VideoController(); 902 @State errorMessage: string = ""; 903 904 build() { 905 Column() { 906 Video({ 907 src: this.videoSrc, 908 controller: this.controller, 909 }) 910 .width(200) 911 .height(120) 912 .margin(5) 913 .autoPlay(this.isAutoPlay) 914 .controls(this.showControls) 915 .onError((err) => { 916 // 通过onError事件获取错误码，code为错误码，message为错误信息。 917 console.error(`code is ${err.code}, message is ${err.message}`); 918 this.errorMessage = `code is ${err.code}, message is ${err.message}`; 919 }) 920 // 传入不存在的视频资源路径，预期："code is 103602, message is Not a valid source"。 921 Text(this.errorMessage) 922 } 923 .width("100%") 924 .height("100%") 925 .backgroundColor('rgb(213,213,213)') 926 } 927} 928``` 929 930 931 932### 示例6（使用attributeModifier动态设置Video组件的属性及方法） 933 934以下示例展示了如何使用attributeModifier动态设置Video组件的enableAnalyzer、analyzerConfig属性和onStart、onPause、onFinish、onError、onStop、onPrepared、onSeeking、onSeeked、onUpdate、onFullscreenChange方法。 935 936```ts 937// xxx.ets 938class MyVideoModifier implements AttributeModifier<VideoAttribute> { 939 applyNormalAttribute(instance: VideoAttribute): void { 940 // 设置开启组件AI分析功能，长按触发AI识别功能 941 instance.enableAnalyzer(true); 942 let config: ImageAnalyzerConfig = { 943 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 944 } 945 instance.analyzerConfig(config); 946 instance.onStart(() => { 947 console.info('video: onStart'); 948 }) 949 instance.onPause(() => { 950 console.info('video: onPause'); 951 }) 952 instance.onFinish(() => { 953 console.info('video: onFinish'); 954 }) 955 instance.onError((err) => { 956 console.error('video: onError is code = ' + err.code + ', message = ' + err.message); 957 }) 958 instance.onStop(() => { 959 console.info('video: onStop'); 960 }) 961 instance.onPrepared((e?: DurationObject) => { 962 if (e != undefined) { 963 console.info('video: onPrepared is ' + e.duration); 964 } 965 }) 966 instance.onSeeking((e?: TimeObject) => { 967 if (e != undefined) { 968 console.info('video: onSeeking is ' + e.time); 969 } 970 }) 971 instance.onSeeked((e?: TimeObject) => { 972 if (e != undefined) { 973 console.info('video: onSeeked is ' + e.time); 974 } 975 }) 976 instance.onUpdate((e?: TimeObject) => { 977 if (e != undefined) { 978 console.info('video: onUpdate is ' + e.time); 979 } 980 }) 981 instance.onFullscreenChange((e?: FullscreenObject) => { 982 if (e != undefined) { 983 console.info('video: onFullscreenChange is ' + e.fullscreen); 984 } 985 }) 986 } 987} 988 989@Entry 990@Component 991struct VideoModifierDemo { 992 // $rawfile('video.mp4')需要替换为开发者所需的视频资源文件 993 @State videoSrc: Resource = $rawfile('video.mp4'); 994 @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X; 995 @State isAutoPlay: boolean = false; 996 @State showControls: boolean = false; 997 controller: VideoController = new VideoController(); 998 @State modifier: MyVideoModifier = new MyVideoModifier(); 999 1000 build() { 1001 Column() { 1002 Video({ 1003 src: this.videoSrc, 1004 currentProgressRate: this.curRate, //设置播放速度 1005 controller: this.controller 1006 }) 1007 .width(300) 1008 .height(180) 1009 .autoPlay(this.isAutoPlay) 1010 .controls(this.showControls) 1011 .attributeModifier(this.modifier) 1012 Row() { 1013 Button('start').onClick(() => { 1014 this.controller.start(); // 开始播放 1015 }).margin(2) 1016 Button('pause').onClick(() => { 1017 this.controller.pause(); // 暂停播放 1018 }).margin(2) 1019 Button('stop').onClick(() => { 1020 this.controller.stop(); // 结束播放 1021 }).margin(2) 1022 Button('reset').onClick(() => { 1023 this.controller.reset(); // 重置AVPlayer 1024 }).margin(2) 1025 } 1026 1027 Row() { 1028 Button('Fullscreen').onClick(() => { 1029 this.controller.requestFullscreen(true); // 全屏 1030 }).margin(2) 1031 Button('showControls').onClick(() => { 1032 this.showControls = !this.showControls; // 显示控制栏 1033 }).margin(2) 1034 } 1035 } 1036 } 1037} 1038 1039interface DurationObject { 1040 duration: number; 1041} 1042 1043interface TimeObject { 1044 time: number; 1045} 1046 1047interface FullscreenObject { 1048 fullscreen: boolean; 1049} 1050``` 1051 1052
