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中CustomBuilder属性将失效。 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 320## VideoController 321 322一个VideoController对象可以控制一个或多个video，可用视频播放实例请参考[@ohos.multimedia.media](../../apis-media-kit/js-apis-media.md)。 323 324**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 325 326**系统能力：** SystemCapability.ArkUI.ArkUI.Full 327 328### 导入对象 329 330```ts 331let controller: VideoController = new VideoController() 332``` 333 334### constructor 335 336constructor() 337 338VideoController的构造函数。 339 340**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 341 342**系统能力：** SystemCapability.ArkUI.ArkUI.Full 343 344### start 345 346start() 347 348开始播放。 349 350**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 351 352**系统能力：** SystemCapability.ArkUI.ArkUI.Full 353 354### pause 355 356pause() 357 358暂停播放，显示当前帧，再次播放时从当前位置继续播放。 359 360**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 361 362**系统能力：** SystemCapability.ArkUI.ArkUI.Full 363 364### stop 365 366stop() 367 368停止播放，显示当前帧，再次播放时从头开始播放。 369 370**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 371 372**系统能力：** SystemCapability.ArkUI.ArkUI.Full 373 374### reset<sup>12+</sup> 375 376reset(): void 377 378video组件重置AVPlayer。显示当前帧，再次播放时从头开始播放。 379 380**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 381 382**系统能力：** SystemCapability.ArkUI.ArkUI.Full 383 384### setCurrentTime 385 386setCurrentTime(value: number) 387 388指定视频播放的进度位置。 389 390**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 391 392**系统能力：** SystemCapability.ArkUI.ArkUI.Full 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ----- | ------ | ---- | -------------- | 398| value | number | 是 | 视频播放进度位置，单位为s。 | 399 400### requestFullscreen 401 402requestFullscreen(value: boolean) 403 404请求全屏播放。 405 406**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 407 408**系统能力：** SystemCapability.ArkUI.ArkUI.Full 409 410**参数：** 411 412| 参数名 | 类型 | 必填 | 说明 | 413| ------ | -------- | ---- | -------------------------------- | 414| value | boolean | 是 | 是否全屏（填充满应用窗口）播放。 | 415 416### exitFullscreen 417 418exitFullscreen() 419 420退出全屏播放。 421 422**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 423 424**系统能力：** SystemCapability.ArkUI.ArkUI.Full 425 426### setCurrentTime<sup>8+</sup> 427 428setCurrentTime(value: number, seekMode: SeekMode) 429 430指定视频播放的进度位置，并指定跳转模式。 431 432**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 433 434**系统能力：** SystemCapability.ArkUI.ArkUI.Full 435 436**参数：** 437 438| 参数名 | 类型 | 必填 | 说明 | 439| -------- | -------- | ---- | -------------- | 440| value | number | 是 | 视频播放进度位置，单位为s。 | 441| seekMode | [SeekMode](#seekmode8枚举说明) | 是 | 跳转模式。 | 442 443## SeekMode<sup>8+</sup>枚举说明 444 445**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 446 447**系统能力：** SystemCapability.ArkUI.ArkUI.Full 448 449| 名称 | 说明 | 450| ---------------- | ---------------------------- | 451| PreviousKeyframe | 跳转到前一个最近的关键帧。 | 452| NextKeyframe | 跳转到后一个最近的关键帧。 | 453| ClosestKeyframe | 跳转到最近的关键帧。 | 454| Accurate | 精准跳转，不论是否为关键帧。 | 455 456## 示例 457 458### 示例1 459 460```ts 461// xxx.ets 462@Entry 463@Component 464struct VideoCreateComponent { 465 @State videoSrc: Resource = $rawfile('video1.mp4') 466 @State previewUri: Resource = $r('app.media.poster1') 467 @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X 468 @State isAutoPlay: boolean = false 469 @State showControls: boolean = true 470 controller: VideoController = new VideoController() 471 472 build() { 473 Column() { 474 Video({ 475 src: this.videoSrc, 476 previewUri: this.previewUri, 477 currentProgressRate: this.curRate, 478 controller: this.controller 479 }) 480 .width('100%') 481 .height(600) 482 .autoPlay(this.isAutoPlay) 483 .controls(this.showControls) 484 .onStart(() => { 485 console.info('onStart') 486 }) 487 .onPause(() => { 488 console.info('onPause') 489 }) 490 .onFinish(() => { 491 console.info('onFinish') 492 }) 493 .onError(() => { 494 console.info('onError') 495 }) 496 .onStop(() => { 497 console.info('onStop') 498 }) 499 .onPrepared((e?: DurationObject) => { 500 if (e != undefined) { 501 console.info('onPrepared is ' + e.duration) 502 } 503 }) 504 .onSeeking((e?: TimeObject) => { 505 if (e != undefined) { 506 console.info('onSeeking is ' + e.time) 507 } 508 }) 509 .onSeeked((e?: TimeObject) => { 510 if (e != undefined) { 511 console.info('onSeeked is ' + e.time) 512 } 513 }) 514 .onUpdate((e?: TimeObject) => { 515 if (e != undefined) { 516 console.info('onUpdate is ' + e.time) 517 } 518 }) 519 520 Row() { 521 Button('src').onClick(() => { 522 this.videoSrc = $rawfile('video2.mp4') // 切换视频源 523 }).margin(5) 524 Button('previewUri').onClick(() => { 525 this.previewUri = $r('app.media.poster2') // 切换视频预览海报 526 }).margin(5) 527 Button('controls').onClick(() => { 528 this.showControls = !this.showControls // 切换是否显示视频控制栏 529 }).margin(5) 530 } 531 532 Row() { 533 Button('start').onClick(() => { 534 this.controller.start() // 开始播放 535 }).margin(2) 536 Button('pause').onClick(() => { 537 this.controller.pause() // 暂停播放 538 }).margin(2) 539 Button('stop').onClick(() => { 540 this.controller.stop() // 结束播放 541 }).margin(2) 542 Button('reset').onClick(() => { 543 this.controller.reset() // 重置AVPlayer 544 }).margin(2) 545 Button('setTime').onClick(() => { 546 this.controller.setCurrentTime(10, SeekMode.Accurate) // 精准跳转到视频的10s位置 547 }).margin(2) 548 } 549 550 Row() { 551 Button('rate 0.75').onClick(() => { 552 this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // 0.75倍速播放 553 }).margin(5) 554 Button('rate 1').onClick(() => { 555 this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // 原倍速播放 556 }).margin(5) 557 Button('rate 2').onClick(() => { 558 this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // 2倍速播放 559 }).margin(5) 560 } 561 } 562 } 563} 564 565interface DurationObject { 566 duration: number; 567} 568 569interface TimeObject { 570 time: number; 571} 572``` 573 574### 示例2 575 576图像分析功能使用示例。 577 578```ts 579// xxx.ets 580@Entry 581@Component 582struct ImageAnalyzerExample { 583 @State videoSrc: Resource = $rawfile('video1.mp4') 584 @State previewUri: Resource = $r('app.media.poster1') 585 @State showControls: boolean = true 586 controller: VideoController = new VideoController() 587 config: ImageAnalyzerConfig = { 588 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 589 } 590 private aiController: ImageAnalyzerController = new ImageAnalyzerController() 591 private options: ImageAIOptions = { 592 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 593 aiController: this.aiController 594 } 595 596 build() { 597 Column() { 598 Video({ 599 src: this.videoSrc, 600 previewUri: this.previewUri, 601 controller: this.controller, 602 imageAIOptions: this.options 603 }) 604 .width('100%') 605 .height(600) 606 .controls(false) 607 .enableAnalyzer(true) 608 .analyzerConfig(this.config) 609 .onStart(() => { 610 console.info('onStart') 611 }) 612 .onPause(() => { 613 console.info('onPause') 614 }) 615 616 Row() { 617 Button('start').onClick(() => { 618 this.controller.start() // 开始播放 619 }).margin(5) 620 Button('pause').onClick(() => { 621 this.controller.pause() // 暂停播放 622 }).margin(5) 623 Button('getTypes').onClick(() => { 624 this.aiController.getImageAnalyzerSupportTypes() 625 }).margin(5) 626 } 627 } 628 } 629} 630```