1# Video 2 3用于播放视频文件并控制其播放状态的组件。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。<br/> 8> Video组件只提供简单的视频播放功能，无法支撑复杂的视频播控场景。复杂开发场景推荐使用[AVPlayer播控API](../../apis-media-kit/js-apis-media.md#avplayer9)和[XComponent](ts-basic-components-xcomponent.md)组件开发。 9 10## 权限列表 11 12使用网络视频时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 13 14 15## 子组件 16 17不支持子组件。 18 19 20## 接口 21 22### Video 23 24Video(value: VideoOptions) 25 26**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 27 28**系统能力：** SystemCapability.ArkUI.ArkUI.Full 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| -------- | -------- | -------- | -------- | 34| value | [VideoOptions](#videooptions对象说明) | 是 | 视频信息。 | 35 36## VideoOptions对象说明 37 38**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42| 名称 | 类型 | 必填 | 说明 | 43| ------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 44| 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/>视频支持的格式是：mp4、mkv、TS。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 45| currentProgressRate | number \| string \| [PlaybackSpeed<sup>8+</sup>](#playbackspeed8枚举说明) | 否 | 视频播放倍速。<br/>**说明：**<br/>number取值仅支持：0.75，1.0，1.25，1.75，2.0。<br/>默认值：1.0 \| PlaybackSpeed.Speed_Forward_1_00_X<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| previewUri | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md) | 否 | 视频未播放时的预览图片路径，默认不显示图片。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| controller | [VideoController](#videocontroller) | 否 | 设置视频控制器，可以控制视频的播放状态。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 48| imageAIOptions<sup>12+</sup> | [ImageAIOptions](ts-image-common.md#imageaioptions) | 否 | 设置图像AI分析选项，可配置分析类型或绑定一个分析控制器。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 49 50## PlaybackSpeed<sup>8+</sup>枚举说明 51 52**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.ArkUI.ArkUI.Full 55 56| 名称 | 说明 | 57| -------------------- | -------------- | 58| Speed_Forward_0_75_X | 0.75倍速播放。 | 59| Speed_Forward_1_00_X | 1倍速播放。 | 60| Speed_Forward_1_25_X | 1.25倍速播放。 | 61| Speed_Forward_1_75_X | 1.75倍速播放。 | 62| Speed_Forward_2_00_X | 2倍速播放。 | 63 64## 属性 65 66除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 67 68### muted 69 70muted(value: boolean) 71 72设置是否静音。 73 74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | ------- | ---- | ---------------------------- | 82| value | boolean | 是 | 是否静音。<br/>默认值：false | 83 84### autoPlay 85 86autoPlay(value: boolean) 87 88设置是否自动播放。 89 90**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 91 92**系统能力：** SystemCapability.ArkUI.ArkUI.Full 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------ | ------- | ---- | -------------------------------- | 98| value | boolean | 是 | 是否自动播放。<br/>默认值：false | 99 100### controls 101 102controls(value: boolean) 103 104设置控制视频播放的控制栏是否显示。 105 106**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| ------ | ------- | ---- | ----------------------------------------------- | 114| value | boolean | 是 | 控制视频播放的控制栏是否显示。<br/>默认值：true | 115 116### objectFit 117 118objectFit(value: ImageFit) 119 120设置视频显示模式。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ----------------------------------------- | ---- | -------------------------------- | 130| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 视频显示模式。<br/>默认值：Cover | 131 132### loop 133 134loop(value: boolean) 135 136设置是否单个视频循环播放。 137 138**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 139 140**系统能力：** SystemCapability.ArkUI.ArkUI.Full 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| ------ | ------- | ---- | ---------------------------------------- | 146| value | boolean | 是 | 是否单个视频循环播放。<br/>默认值：false | 147 148### enableAnalyzer<sup>12+</sup> 149 150enableAnalyzer(enable: boolean) 151 152设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。 153使能后，视频播放暂停时自动进入分析状态，开始分析当前画面帧，视频继续播放后自动退出分析状态。 154不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时[overlay](ts-universal-attributes-overlay.md)中[CustomBuilder](ts-types.md#custombuilder8)属性将失效。 155 156**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 157 158**系统能力：** SystemCapability.ArkUI.ArkUI.Full 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| -------- | -------- | -------- | -------- | 164| enable | boolean | 是 | 是否启用AI分析功能 | 165 166> **说明：** 167> 168> 当前仅在使用自定义控制栏([controls](#controls)属性设置为false)时支持该功能。 169> 该特性依赖设备能力。 170 171### analyzerConfig<sup>12+</sup> 172 173analyzerConfig(config: ImageAnalyzerConfig) 174 175设置AI分析识别类型，包括主体识别、文字识别和对象查找等功能。 176 177**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181| 参数名 | 类型 | 必填 | 说明 | 182| -------- | -------- | -------- | -------- | 183| config | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig) | 是 | 设置AI分析识别类型 | 184 185## 事件 186 187除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 188 189### onStart 190 191onStart(event:() => void) 192 193播放时触发该事件。 194 195**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199### onPause 200 201onPause(event:() => void) 202 203暂停时触发该事件。 204 205**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 206 207**系统能力：** SystemCapability.ArkUI.ArkUI.Full 208 209### onFinish 210 211onFinish(event:() => void) 212 213播放结束时触发该事件。 214 215**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 216 217**系统能力：** SystemCapability.ArkUI.ArkUI.Full 218 219### onError 220 221onError(event:() => void) 222 223播放失败时触发该事件。 224 225**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 226 227**系统能力：** SystemCapability.ArkUI.ArkUI.Full 228 229### onStop<sup>12+</sup> 230 231onStop(event: Callback<void>) 232 233播放停止时触发该事件(当stop()方法被调用后触发)。 234 235**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239### onPrepared 240 241onPrepared(callback:(event: { duration: number }) => void) 242 243视频准备完成时触发该事件。 244 245**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 246 247**系统能力：** SystemCapability.ArkUI.ArkUI.Full 248 249**参数：** 250 251| 参数名 | 类型 | 必填 | 说明 | 252| -------- | ------ | ---- | -------------------------- | 253| duration | number | 是 | 当前视频的时长，单位为秒。 | 254 255### onSeeking 256 257onSeeking(callback:(event: { time: number }) => void) 258 259操作进度条过程时上报时间信息。 260 261**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 262 263**系统能力：** SystemCapability.ArkUI.ArkUI.Full 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| ------ | ------ | ---- | ------------------------------ | 269| time | number | 是 | 当前视频播放的进度，单位为秒。 | 270 271### onSeeked 272 273onSeeked(callback:(event: { time: number }) => void) 274 275操作进度条完成后，上报播放时间信息。 276 277**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 278 279**系统能力：** SystemCapability.ArkUI.ArkUI.Full 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| ------ | ------ | ---- | ------------------------------ | 285| time | number | 是 | 当前视频播放的进度，单位为秒。 | 286 287### onUpdate 288 289onUpdate(callback:(event: { time: number }) => void) 290 291播放进度变化时触发该事件。 292 293**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 294 295**系统能力：** SystemCapability.ArkUI.ArkUI.Full 296 297**参数：** 298 299| 参数名 | 类型 | 必填 | 说明 | 300| ------ | ------ | ---- | ------------------------------ | 301| time | number | 是 | 当前视频播放的进度，单位为秒。 | 302 303### onFullscreenChange 304 305onFullscreenChange(callback:(event: { fullscreen: boolean }) => void) 306 307在全屏播放与非全屏播放状态之间切换时触发该事件。 308 309**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 310 311**系统能力：** SystemCapability.ArkUI.ArkUI.Full 312 313**参数：** 314 315| 参数名 | 类型 | 必填 | 说明 | 316| ---------- | ------- | ---- | ----------------------------------------------------- | 317| fullscreen | boolean | 是 | 为true表示进入全屏播放状态，为false则表示非全屏播放。 | 318 319## VideoController 320 321一个VideoController对象可以控制一个或多个video，可用视频播放实例请参考[@ohos.multimedia.media](../../apis-media-kit/js-apis-media.md)。 322 323**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.ArkUI.ArkUI.Full 326 327### 导入对象 328 329```ts 330let controller: VideoController = new VideoController() 331``` 332 333### constructor 334 335constructor() 336 337VideoController的构造函数。 338 339**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 340 341**系统能力：** SystemCapability.ArkUI.ArkUI.Full 342 343### start 344 345start() 346 347开始播放。 348 349**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 350 351**系统能力：** SystemCapability.ArkUI.ArkUI.Full 352 353### pause 354 355pause() 356 357暂停播放，显示当前帧，再次播放时从当前位置继续播放。 358 359**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 360 361**系统能力：** SystemCapability.ArkUI.ArkUI.Full 362 363### stop 364 365stop() 366 367停止播放，显示当前帧，再次播放时从头开始播放。 368 369**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 370 371**系统能力：** SystemCapability.ArkUI.ArkUI.Full 372 373### reset<sup>12+</sup> 374 375reset(): void 376 377video组件重置AVPlayer。显示当前帧，再次播放时从头开始播放。 378 379**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 380 381**系统能力：** SystemCapability.ArkUI.ArkUI.Full 382 383### setCurrentTime 384 385setCurrentTime(value: number) 386 387指定视频播放的进度位置。 388 389**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 390 391**系统能力：** SystemCapability.ArkUI.ArkUI.Full 392 393**参数：** 394 395| 参数名 | 类型 | 必填 | 说明 | 396| ----- | ------ | ---- | -------------- | 397| value | number | 是 | 视频播放进度位置，单位为s。 | 398 399### requestFullscreen 400 401requestFullscreen(value: boolean) 402 403请求全屏播放。 404 405**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 406 407**系统能力：** SystemCapability.ArkUI.ArkUI.Full 408 409**参数：** 410 411| 参数名 | 类型 | 必填 | 说明 | 412| ------ | -------- | ---- | -------------------------------- | 413| value | boolean | 是 | 是否全屏（填充满应用窗口）播放。 | 414 415### exitFullscreen 416 417exitFullscreen() 418 419退出全屏播放。 420 421**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 422 423**系统能力：** SystemCapability.ArkUI.ArkUI.Full 424 425### setCurrentTime<sup>8+</sup> 426 427setCurrentTime(value: number, seekMode: SeekMode) 428 429指定视频播放的进度位置，并指定跳转模式。 430 431**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 432 433**系统能力：** SystemCapability.ArkUI.ArkUI.Full 434 435**参数：** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| -------- | -------- | ---- | -------------- | 439| value | number | 是 | 视频播放进度位置，单位为s。 | 440| seekMode | [SeekMode](#seekmode8枚举说明) | 是 | 跳转模式。 | 441 442## SeekMode<sup>8+</sup>枚举说明 443 444**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 445 446**系统能力：** SystemCapability.ArkUI.ArkUI.Full 447 448| 名称 | 说明 | 449| ---------------- | ---------------------------- | 450| PreviousKeyframe | 跳转到前一个最近的关键帧。 | 451| NextKeyframe | 跳转到后一个最近的关键帧。 | 452| ClosestKeyframe | 跳转到最近的关键帧。 | 453| Accurate | 精准跳转，不论是否为关键帧。 | 454 455## 示例 456 457### 示例1（视频播放基础用法） 458 459基础用法，包括控制栏、预览图、自动播放、播放速度、控制器（开始播放、暂停播放、停止播放、重置avPlayer、跳转等）以及一些状态回调方法。 460 461```ts 462// xxx.ets 463@Entry 464@Component 465struct VideoCreateComponent { 466 @State videoSrc: Resource = $rawfile('video1.mp4') 467 @State previewUri: Resource = $r('app.media.poster1') 468 @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X 469 @State isAutoPlay: boolean = false 470 @State showControls: boolean = true 471 controller: VideoController = new VideoController() 472 473 build() { 474 Column() { 475 Video({ 476 src: this.videoSrc, 477 previewUri: this.previewUri, 478 currentProgressRate: this.curRate, 479 controller: this.controller 480 }) 481 .width('100%') 482 .height(600) 483 .autoPlay(this.isAutoPlay) 484 .controls(this.showControls) 485 .onStart(() => { 486 console.info('onStart') 487 }) 488 .onPause(() => { 489 console.info('onPause') 490 }) 491 .onFinish(() => { 492 console.info('onFinish') 493 }) 494 .onError(() => { 495 console.info('onError') 496 }) 497 .onStop(() => { 498 console.info('onStop') 499 }) 500 .onPrepared((e?: DurationObject) => { 501 if (e != undefined) { 502 console.info('onPrepared is ' + e.duration) 503 } 504 }) 505 .onSeeking((e?: TimeObject) => { 506 if (e != undefined) { 507 console.info('onSeeking is ' + e.time) 508 } 509 }) 510 .onSeeked((e?: TimeObject) => { 511 if (e != undefined) { 512 console.info('onSeeked is ' + e.time) 513 } 514 }) 515 .onUpdate((e?: TimeObject) => { 516 if (e != undefined) { 517 console.info('onUpdate is ' + e.time) 518 } 519 }) 520 521 Row() { 522 Button('src').onClick(() => { 523 this.videoSrc = $rawfile('video2.mp4') // 切换视频源 524 }).margin(5) 525 Button('previewUri').onClick(() => { 526 this.previewUri = $r('app.media.poster2') // 切换视频预览海报 527 }).margin(5) 528 Button('controls').onClick(() => { 529 this.showControls = !this.showControls // 切换是否显示视频控制栏 530 }).margin(5) 531 } 532 533 Row() { 534 Button('start').onClick(() => { 535 this.controller.start() // 开始播放 536 }).margin(2) 537 Button('pause').onClick(() => { 538 this.controller.pause() // 暂停播放 539 }).margin(2) 540 Button('stop').onClick(() => { 541 this.controller.stop() // 结束播放 542 }).margin(2) 543 Button('reset').onClick(() => { 544 this.controller.reset() // 重置AVPlayer 545 }).margin(2) 546 Button('setTime').onClick(() => { 547 this.controller.setCurrentTime(10, SeekMode.Accurate) // 精准跳转到视频的10s位置 548 }).margin(2) 549 } 550 551 Row() { 552 Button('rate 0.75').onClick(() => { 553 this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // 0.75倍速播放 554 }).margin(5) 555 Button('rate 1').onClick(() => { 556 this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // 原倍速播放 557 }).margin(5) 558 Button('rate 2').onClick(() => { 559 this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // 2倍速播放 560 }).margin(5) 561 } 562 } 563 } 564} 565 566interface DurationObject { 567 duration: number; 568} 569 570interface TimeObject { 571 time: number; 572} 573``` 574 575### 示例2（图像分析功能） 576 577使用enableAnalyzer属性开启图像AI分析。 578 579```ts 580// xxx.ets 581@Entry 582@Component 583struct ImageAnalyzerExample { 584 @State videoSrc: Resource = $rawfile('video1.mp4') 585 @State previewUri: Resource = $r('app.media.poster1') 586 @State showControls: boolean = true 587 controller: VideoController = new VideoController() 588 config: ImageAnalyzerConfig = { 589 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 590 } 591 private aiController: ImageAnalyzerController = new ImageAnalyzerController() 592 private options: ImageAIOptions = { 593 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 594 aiController: this.aiController 595 } 596 597 build() { 598 Column() { 599 Video({ 600 src: this.videoSrc, 601 previewUri: this.previewUri, 602 controller: this.controller, 603 imageAIOptions: this.options 604 }) 605 .width('100%') 606 .height(600) 607 .controls(false) 608 .enableAnalyzer(true) 609 .analyzerConfig(this.config) 610 .onStart(() => { 611 console.info('onStart') 612 }) 613 .onPause(() => { 614 console.info('onPause') 615 }) 616 617 Row() { 618 Button('start').onClick(() => { 619 this.controller.start() // 开始播放 620 }).margin(5) 621 Button('pause').onClick(() => { 622 this.controller.pause() // 暂停播放 623 }).margin(5) 624 Button('getTypes').onClick(() => { 625 this.aiController.getImageAnalyzerSupportTypes() 626 }).margin(5) 627 } 628 } 629 } 630} 631``` 632 633### 示例3（播放拖入的视频） 634 635以下示例展示了如何使Video组件能够播放拖入的视频。 636 637```ts 638import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData'; 639 640@Entry 641@Component 642struct Index { 643 @State videoSrc: Resource | string = $rawfile('video1.mp4'); 644 private controller: VideoController = new VideoController(); 645 646 build() { 647 Column() { 648 Video({ 649 src: this.videoSrc, 650 controller: this.controller 651 }) 652 .width('100%') 653 .height(600) 654 .onPrepared(() => { 655 // 在onPrepared回调中执行controller的start方法，确保视频源更换后直接开始播放。 656 this.controller.start(); 657 }) 658 .onDrop((e: DragEvent) => { 659 // 外部视频拖入应用Video组件范围，松手后触发通过onDrop注册的回调。 660 // 在DragEvent中会包含拖入的视频源信息，取出后赋值给状态变量videoSrc即可改变Video的视频源。 661 let record = e.getData().getRecords()[0]; 662 if (record.getType() == uniformTypeDescriptor.UniformDataType.VIDEO) { 663 let videoInfo = record as unifiedDataChannel.Video; 664 this.videoSrc = videoInfo.videoUri; 665 } 666 }) 667 } 668 } 669} 670``` 671