1# @ohos.PiPWindow (画中画窗口) 2 3该模块提供画中画基础功能,包括判断当前系统是否开启画中画功能,以及创建画中画控制器用于启动、停止画中画等。主要用于视频播放、视频通话或视频会议场景下,以小窗(画中画)模式呈现内容。 4 5> **说明:** 6> 7> 本模块首批接口从API version 11开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 8> 9> 需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块,<!--RP1-->参考[系统能力SystemCapability使用指南](../syscap.md)<!--RP1End-->。 10 11## 导入模块 12 13```ts 14import { PiPWindow } from '@kit.ArkUI'; 15``` 16 17## PiPWindow.isPiPEnabled 18 19isPiPEnabled(): boolean 20 21用于判断当前系统是否支持画中画功能。 22 23**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 24 25**系统能力:** SystemCapability.Window.SessionManager 26 27**返回值:** 28 29| 类型 | 说明 | 30|----------|-------------------------------------| 31| boolean | 当前系统是否开启画中画功能。true表示支持,false则表示不支持。 | 32 33**示例:** 34 35```ts 36let enable: boolean = PiPWindow.isPiPEnabled(); 37console.info('isPipEnabled:' + enable); 38``` 39 40## PiPWindow.create 41 42create(config: PiPConfiguration): Promise<PiPController> 43 44创建画中画控制器,使用Promise异步回调。 45 46**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 47 48**系统能力:** SystemCapability.Window.SessionManager 49 50**参数:** 51 52| 参数名 | 类型 | 必填 | 说明 | 53|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 54| config | [PiPConfiguration](#pipconfiguration) | 是 | 创建画中画控制器的参数。该参数不能为空,并且构造该参数的context和componentController不能为空。构造该参数时,如果指定了templateType,需保证templateType是[PiPTemplateType](#piptemplatetype)类型;如果指定了controlGroups,需保证controlGroups与templateType匹配,详见[PiPControlGroup](#pipcontrolgroup12)。 | 55 56**返回值:** 57 58| 类型 | 说明 | 59|------------------------------------------------------------|--------------------------| 60| Promise<[PiPController](#pipcontroller)> | Promise对象。返回当前创建的画中画控制器。 | 61 62**错误码:** 63 64以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 65 66| 错误码ID | 错误信息 | 67|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 68| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 69| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 70 71**示例:** 72 73```ts 74import { BusinessError } from '@kit.BasicServicesKit'; 75import { BuilderNode, FrameNode, NodeController, Size, UIContext } from '@kit.ArkUI'; 76 77class Params { 78 text: string = ''; 79 constructor(text: string) { 80 this.text = text; 81 } 82} 83 84// 开发者可以通过@Builder装饰器实现布局构建 85@Builder 86function buildText(params: Params) { 87 Column() { 88 Text(params.text) 89 .fontSize(20) 90 .fontColor(Color.Red) 91 } 92 .width('100%') // 宽度方向充满画中画窗口 93 .height('100%') // 高度方向充满画中画窗口 94} 95 96// 开发者可通过继承NodeController实现自定义UI控制器 97class TextNodeController extends NodeController { 98 private message: string; 99 private textNode: BuilderNode<[Params]> | null = null; 100 constructor(message: string) { 101 super(); 102 this.message = message; 103 } 104 105 // 通过BuilderNode加载自定义布局 106 makeNode(context: UIContext): FrameNode | null { 107 this.textNode = new BuilderNode(context); 108 this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message)); 109 return this.textNode.getFrameNode(); 110 } 111 112 // 开发者可自定义该方法实现布局更新 113 update(message: string) { 114 console.log(`update message: ${message}`); 115 if (this.textNode !== null) { 116 this.textNode.update(new Params(message)); 117 } 118 } 119} 120 121let pipController: PiPWindow.PiPController | undefined = undefined; 122let mXComponentController: XComponentController = new XComponentController(); // 开发者应使用该mXComponentController初始化XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} ),保证XComponent的内容可以被迁移到画中画窗口。 123let nodeController: TextNodeController = new TextNodeController('this is custom UI'); 124let navId: string = "page_1"; // 假设当前页面的导航id为page_1,详见PiPConfiguration定义,具体导航名称由开发者自行定义。 125let contentWidth: number = 800; // 假设当前内容宽度800px。 126let contentHeight: number = 600; // 假设当前内容高度600px。 127let config: PiPWindow.PiPConfiguration = { 128 context: getContext(this), 129 componentController: mXComponentController, 130 navigationId: navId, 131 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 132 contentWidth: contentWidth, 133 contentHeight: contentHeight, 134 controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], 135 customUIController: nodeController, // 可选,如果需要在画中画显示内容上方展示自定义UI,可设置该参数。 136}; 137 138let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config); 139promise.then((data : PiPWindow.PiPController) => { 140 pipController = data; 141 console.info(`Succeeded in creating pip controller. Data:${data}`); 142}).catch((err: BusinessError) => { 143 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 144}); 145``` 146 147## PiPWindow.create<sup>12+</sup> 148 149create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise<PiPController> 150 151通过typeNode创建画中画控制器,使用Promise异步回调。 152 153**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 154 155**系统能力:** SystemCapability.Window.SessionManager 156 157**参数:** 158 159| 参数名 | 类型 | 必填 | 说明 | 160|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 161| config | [PiPConfiguration](#pipconfiguration) | 是 | 创建画中画控制器的参数。该参数不能为空,并且构造该参数的context不能为空。构造该参数时,如果指定了templateType,需保证templateType是[PiPTemplateType](#piptemplatetype)类型;如果指定了controlGroups,需保证controlGroups与templateType匹配,详见[PiPControlGroup](#pipcontrolgroup12)。 | 162| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | 是 | 用于渲染画中画窗口中的内容。该参数不能为空。| 163 164**返回值:** 165 166| 类型 | 说明 | 167|------------------------------------------------------------|--------------------------| 168| Promise<[PiPController](#pipcontroller)> | Promise对象。返回当前创建的画中画控制器。 | 169 170**错误码:** 171 172以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 173 174| 错误码ID | 错误信息 | 175|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 176| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 177| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 178 179**示例:** 180 181```ts 182import { BusinessError } from '@kit.BasicServicesKit'; 183import { PiPWindow, UIContext } from '@kit.ArkUI'; 184import { typeNode } from '@ohos.arkui.node'; 185 186let pipController: PiPWindow.PiPController | undefined = undefined; 187let xComponentController: XComponentController = new XComponentController(); 188let context: UIContext | undefined = undefined; // 可传入UIContext或在布局中通过this.getUIContext()为context赋有效值 189let xComponent = typeNode.createNode(context, 'XComponent'); 190xComponent.initialize({ 191 id:'xcomponent', 192 type:XComponentType.SURFACE, 193 controller:xComponentController 194}); 195let contentWidth: number = 800; // 假设当前内容宽度800px。 196let contentHeight: number = 600; // 假设当前内容高度600px。 197let config: PiPWindow.PiPConfiguration = { 198 context: getContext(this), 199 componentController: xComponentController, 200 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 201 contentWidth: contentWidth, 202 contentHeight: contentHeight 203}; 204 205let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config, xComponent); 206promise.then((data : PiPWindow.PiPController) => { 207 pipController = data; 208 console.info(`Succeeded in creating pip controller. Data:${data}`); 209}).catch((err: BusinessError) => { 210 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 211}); 212``` 213 214## PiPConfiguration 215 216创建画中画控制器时的参数。 217 218**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 219 220**系统能力:** SystemCapability.Window.SessionManager 221 222| 名称 | 类型 | 必填 | 说明 | 223|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 224| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 表示上下文环境。 | 225| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md) | 是 | 表示原始[XComponent](arkui-ts/ts-basic-components-xcomponent.md)控制器。 | 226| navigationId | string | 否 | 当前page导航id。<br/>1、UIAbility使用[Navigation](arkui-ts/ts-basic-components-navigation.md)管理页面,需要设置Navigation控件的id属性,并将该id设置给画中画控制器,确保还原场景下能够从画中画窗口恢复到原页面。<br/>2、UIAbility使用[Router](js-apis-router.md)管理页面时,无需设置navigationId。<br/>3、UIAbility只有单页面时,无需设置navigationId,还原场景下也能够从画中画窗口恢复到原页面。 | 227| templateType | [PiPTemplateType](#piptemplatetype) | 否 | 模板类型,用以区分视频播放、视频通话或视频会议。 | 228| contentWidth | number | 否 | 原始内容宽度,单位为px。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时,不传值则默认为1920。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时,不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的宽度。 | 229| contentHeight | number | 否 | 原始内容高度,单位为px。用于确定画中画窗口比例。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时,不传值则默认为1080。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时,不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的高度。 | 230| controlGroups<sup>12+</sup> | Array<[PiPControlGroup](#pipcontrolgroup12)> | 否 | 画中画控制面板的可选控件组列表,应用可以对此进行配置以决定是否显示。如果应用没有配置,面板将显示基础控件(如视频播放控件组的播放/暂停控件);如果应用选择配置,则最多可以选择三个控件。从API version 12开始支持此参数。 | 231| customUIController<sup>12+</sup> | [NodeController](js-apis-arkui-nodeController.md) | 否 | 用于实现在画中画界面内容上方展示自定义UI功能。从API version 12开始支持此参数。 | 232 233## PiPTemplateType 234 235画中画媒体类型枚举。 236 237**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 238 239**系统能力:** SystemCapability.Window.SessionManager 240 241| 名称 | 值 | 说明 | 242|---------------|-----|--------------------------------------| 243| VIDEO_PLAY | 0 | 表示将要切换为画中画播放的媒体类型是视频,系统依此加载视频播放模板。 | 244| VIDEO_CALL | 1 | 表示将要切换为画中画播放的媒体类型是视频通话,系统依此加载视频通话模板。 | 245| VIDEO_MEETING | 2 | 表示将要切换为画中画播放的媒体类型是视频会议,系统依此加载视频会议模板。 | 246| VIDEO_LIVE | 3 | 表示将要切换为画中画播放的媒体类型是直播,系统依此加载直播模板。 | 247 248## PiPState 249 250画中画生命周期状态枚举。 251 252**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 253 254**系统能力:** SystemCapability.Window.SessionManager 255 256| 名称 | 值 | 说明 | 257|----------------------|-----|-----------------------| 258| ABOUT_TO_START | 1 | 表示画中画将要启动。 | 259| STARTED | 2 | 表示画中画已经启动。 | 260| ABOUT_TO_STOP | 3 | 表示画中画将要停止。 | 261| STOPPED | 4 | 表示画中画已经停止。 | 262| ABOUT_TO_RESTORE | 5 | 表示画中画将从小窗播放恢复到原始播放界面。 | 263| ERROR | 6 | 表示画中画生命周期执行过程出现了异常。 | 264 265## PiPControlGroup<sup>12+</sup> 266 267type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 268 269画中画控制面板的可选控件组列表,应用可以配置是否显示可选控件。默认情况下控制面板只显示基础控件(如视频播放控件组的播放/暂停控件)。 270 271**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 272 273**系统能力:** SystemCapability.Window.SessionManager 274 275| 类型 | 说明 | 276|-------------------------------------------------|-------------| 277| [VideoPlayControlGroup](#videoplaycontrolgroup12) | 视频播放控件组。 | 278| [VideoCallControlGroup](#videocallcontrolgroup12) | 视频通话控件组。 | 279| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | 视频会议控件组。 | 280| [VideoLiveControlGroup](#videolivecontrolgroup12) | 视频直播控件组。 | 281 282 283## VideoPlayControlGroup<sup>12+</sup> 284 285视频播放控件组枚举。仅当[PiPTemplateType](#piptemplatetype)为VIDEO_PLAY时使用。 286 287**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 288 289**系统能力:** SystemCapability.Window.SessionManager 290 291| 名称 | 值 | 说明 | 292|----------------------|-----|-----------------------| 293| VIDEO_PREVIOUS_NEXT | 101 | 视频上一个/下一个控件组。<br/>与视频快进/后退控件组为互斥控件组。如添加视频快进/后退控件组,则不可添加该控件组。 | 294| FAST_FORWARD_BACKWARD | 102 | 视频快进/后退控件组。<br/>与视频上一个/下一个控件组为互斥控件组。如添加视频上一个/下一个控件组,则不可添加该控件组。 | 295 296## VideoCallControlGroup<sup>12+</sup> 297 298视频通话控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_CALL时使用。 299 300**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 301 302**系统能力:** SystemCapability.Window.SessionManager 303 304| 名称 | 值 | 说明 | 305|----------------------|-----|-----------------------| 306| MICROPHONE_SWITCH | 201 | 打开/关闭麦克风控件组。 | 307| HANG_UP_BUTTON | 202 | 挂断控件组。 | 308| CAMERA_SWITCH | 203 | 打开/关闭摄像头控件组。 | 309| MUTE_SWITCH | 204 | 静音控件组。 | 310 311## VideoMeetingControlGroup<sup>12+</sup> 312 313视频会议控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_MEETING时使用。 314 315**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 316 317**系统能力:** SystemCapability.Window.SessionManager 318 319| 名称 | 值 | 说明 | 320|----------------------|-----|-----------------------| 321| HANG_UP_BUTTON | 301 | 挂断控件组。 | 322| CAMERA_SWITCH | 302 | 打开/关闭摄像头控件组。 | 323| MUTE_SWITCH | 303 | 静音控件组。 | 324| MICROPHONE_SWITCH | 304 | 打开/关闭麦克风控件组。 | 325 326## VideoLiveControlGroup<sup>12+</sup> 327 328视频直播控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_LIVE时使用。 329 330**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 331 332**系统能力:** SystemCapability.Window.SessionManager 333 334| 名称 | 值 | 说明 | 335|----------------------|-----|-----------------------| 336| VIDEO_PLAY_PAUSE | 401 | 播放/暂停直播控件组 | 337| MUTE_SWITCH | 402 | 静音控件组。 | 338 339## PiPActionEventType 340 341type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 342 343画中画控制面板控件动作事件类型,支持以下四种。 344 345**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 346 347**系统能力:** SystemCapability.Window.SessionManager 348 349| 类型 | 说明 | 350|-------------------------------------------------|-------------| 351| [PiPVideoActionEvent](#pipvideoactionevent) | 视频播放控制面板控件事件类型。 | 352| [PiPCallActionEvent](#pipcallactionevent) | 视频通话控制面板控件事件类型。 | 353| [PiPMeetingActionEvent](#pipmeetingactionevent) | 视频会议控制面板控件事件类型。 | 354| [PiPLiveActionEvent](#pipliveactionevent) | 直播控制面板控件事件类型。 | 355 356## PiPVideoActionEvent 357 358type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 359 360视频播放控制事件类型。 361 362**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 363 364**系统能力:** SystemCapability.Window.SessionManager 365 366| 类型 | 说明 | 367| ---------------------------- | ----------------------------------------- | 368| 'playbackStateChanged' | 播放状态发生了变化。 | 369| 'nextVideo' | 播放下一个视频。 | 370| 'previousVideo' | 播放上一个视频。 | 371| 'fastForward'<sup>12+</sup> | 视频进度快进。从API version 12 开始支持。 | 372| 'fastBackward'<sup>12+</sup> | 视频进度后退。从API version 12 开始支持。 | 373 374## PiPCallActionEvent 375 376type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 377 378视频通话控制事件类型。 379 380**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 381 382**系统能力:** SystemCapability.Window.SessionManager 383 384| 类型 | 说明 | 385| ------------------- | ------------------ | 386| 'hangUp' | 挂断视频通话。 | 387| 'micStateChanged' | 打开或关闭麦克风。 | 388| 'videoStateChanged' | 打开或关闭摄像头。 | 389| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 390 391 392## PiPMeetingActionEvent 393 394type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 395 396视频会议控制事件类型。 397 398**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 399 400**系统能力:** SystemCapability.Window.SessionManager 401 402| 类型 | 说明 | 403| ------------------- | ------------------ | 404| 'hangUp' | 挂断视频会议。 | 405| 'voiceStateChanged' | 静音或解除静音。 | 406| 'videoStateChanged' | 打开或关闭摄像头。 | 407| 'micStateChanged'<sup>12+</sup> | 打开或关闭麦克风。 | 408 409 410## PiPLiveActionEvent 411 412type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 413 414直播控制事件类型。 415 416**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 417 418**系统能力:** SystemCapability.Window.SessionManager 419 420| 类型 | 说明 | 421| ---------------------- | ---------------- | 422| 'playbackStateChanged' | 播放或暂停直播。 | 423| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 424 425 426## PiPControlStatus<sup>12+</sup> 427 428控制面板控件状态枚举。 429 430**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 431 432**系统能力:** SystemCapability.Window.SessionManager 433 434| 名称 | 值 | 说明 | 435|----------------------|-----|-----------------------| 436| PLAY | 1 | 播放。 | 437| PAUSE | 0 | 暂停。 | 438| OPEN | 1 | 打开。 | 439| CLOSE | 0 | 关闭。 | 440 441## PiPControlType<sup>12+</sup> 442 443控制面板控件类型枚举。 444 445**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 446 447**系统能力:** SystemCapability.Window.SessionManager 448 449| 名称 | 值 | 说明 | 450|-------------------|-----|--------------------------------------| 451| VIDEO_PLAY_PAUSE | 0 | 播放/暂停控件。 | 452| VIDEO_PREVIOUS | 1 | 视频上一个控件。 | 453| VIDEO_NEXT | 2 | 视频下一个控件。 | 454| FAST_FORWARD | 3 | 视频快进控件 | 455| FAST_BACKWARD | 4 | 视频快退控件。 | 456| HANG_UP_BUTTON | 5 | 挂断控件。 | 457| MICROPHONE_SWITCH | 6 | 打开/关闭麦克风控件。 | 458| CAMERA_SWITCH | 7 | 打开/关闭摄像头控件。 | 459| MUTE_SWITCH | 8 | 打开/关闭静音控件。 | 460 461 462## ControlPanelActionEventCallback<sup>12+</sup> 463 464type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 465 466描述画中画控制面板控件动作事件回调。 467 468**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 469 470**系统能力:** SystemCapability.Window.SessionManager 471 472**参数:** 473 474| 参数名 | 类型 | 必填 | 说明 | 475|--------------------------|--------------|--------------|-----------------------------------| 476| event | [PiPActionEventType](#pipactioneventtype) | 是 | 回调画中画控制面板控件动作事件类型。<br/>应用依据控件动作事件做相应处理,如触发'playbackStateChanged'事件时,需要开始或停止视频。 | 477| status | number | 否 | 表示可切换状态的控件当前的状态,如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组,打开为1,关闭为0。其余控件该参数返回默认值-1。 | 478 479## ControlEventParam<sup>12+</sup> 480 481画中画控制面板控件动作回调的参数。 482 483**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 484 485**系统能力:** SystemCapability.Window.SessionManager 486 487| 名称 | 类型 | 必填 | 说明 | 488|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 489| controlType | [PiPControlType](#pipcontroltype12) | 是 | 回调画中画控制面板控件动作事件类型。应用依据控件类型做相应处理,如视频模板中暂停/播放控件被点击时,需要开始或停止视频。 | 490| status | [PiPControlStatus](#pipcontrolstatus12) | 否 | 表示可切换状态的控件当前的状态,如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组,打开为PiPControlStatus.PLAY,关闭为PiPControlStatus.PAUSE。如不具备开/关和播放/暂停状态的挂断控件默认返回值为-1。 | 491 492## PiPController 493 494画中画控制器实例。用于启动、停止画中画以及更新回调注册等。 495 496下列API示例中都需先使用[PiPWindow.create()](#pipwindowcreate)方法获取到PiPController实例,再通过此实例调用对应方法。 497 498**系统能力:** SystemCapability.Window.SessionManager 499 500### startPiP 501 502startPiP(): Promise<void> 503 504启动画中画,使用Promise异步回调。 505 506**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 507 508**系统能力:** SystemCapability.Window.SessionManager 509 510**返回值:** 511 512| 类型 | 说明 | 513|------------------------|--------------------| 514| Promise<void> | 无返回结果的Promise对象。 | 515 516**错误码:** 517 518以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 519 520| 错误码ID | 错误信息 | 521|------------|--------------------------------------------------------| 522| 1300012 | The PiP window state is abnormal. | 523| 1300013 | Failed to create the PiP window. | 524| 1300014 | PiP internal error. | 525| 1300015 | Repeated PiP operation. | 526 527**示例:** 528 529```ts 530let promise : Promise<void> = pipController.startPiP(); 531promise.then(() => { 532 console.info(`Succeeded in starting pip.`); 533}).catch((err: BusinessError) => { 534 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 535}); 536``` 537 538### stopPiP 539 540stopPiP(): Promise<void> 541 542停止画中画,使用Promise异步回调。 543 544**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 545 546**系统能力:** SystemCapability.Window.SessionManager 547 548**返回值:** 549 550| 类型 | 说明 | 551|----------------------|---------------------| 552| Promise<void> | 无返回结果的Promise对象。 | 553 554**错误码:** 555 556以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 557 558| 错误码ID | 错误信息 | 559|---------|-----------------------------------| 560| 1300011 | Failed to destroy the PiP window. | 561| 1300012 | The PiP window state is abnormal. | 562| 1300015 | Repeated PiP operation. | 563 564**示例:** 565 566```ts 567let promise : Promise<void> = pipController.stopPiP(); 568promise.then(() => { 569 console.info(`Succeeded in stopping pip.`); 570}).catch((err: BusinessError) => { 571 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 572}); 573``` 574 575### setAutoStartEnabled 576 577setAutoStartEnabled(enable: boolean): void 578 579设置是否需要在返回桌面时自动启动画中画。 580 581**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 582 583**系统能力:** SystemCapability.Window.SessionManager 584 585**参数:** 586 587| 参数名 | 类型 | 必填 | 说明 | 588|----------|-----------|-------|---------------------------------| 589| enable | boolean | 是 | 如返回桌面时需自动启动画中画,则该参数配置为true,否则为false。若设置中自动启动画中画开关为关闭状态,就算该参数配置为true,应用返回桌面时也不会自动启动画中画窗口。 | 590 591**示例:** 592 593```ts 594let enable: boolean = true; 595pipController.setAutoStartEnabled(enable); 596``` 597 598### updateContentSize 599 600updateContentSize(width: number, height: number): void 601 602当媒体源切换时,向画中画控制器更新媒体源尺寸信息。 603 604**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 605 606**系统能力:** SystemCapability.Window.SessionManager 607 608**参数:** 609 610| 参数名 | 类型 | 必填 | 说明 | 611|--------|--------|-----|----------------------------------------| 612| width | number | 是 | 表示媒体内容宽度,必须为大于0的数字,单位为px。用于更新画中画窗口比例。 | 613| height | number | 是 | 表示媒体内容高度,必须为大于0的数字,单位为px。用于更新画中画窗口比例。 | 614 615**错误码:** 616 617以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 618 619| 错误码ID | 错误信息 | 620|-------|-------------------------------------------------------------------------------------------------------------| 621| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 622 623**示例:** 624 625```ts 626let width: number = 540; // 假设当前内容宽度变为540px。 627let height: number = 960; // 假设当前内容高度变为960px。 628pipController.updateContentSize(width, height); 629``` 630 631### updatePiPControlStatus<sup>12+</sup> 632updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 633 634更新控制面板控件功能状态。 635 636**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 637 638**系统能力:** SystemCapability.Window.SessionManager 639 640**参数:** 641 642| 参数名 | 类型 | 必填 | 说明 | 643|--------|--------|-----|----------------------------------------------------------------------------------------------------| 644| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。目前仅支持VIDEO_PLAY_PAUSE、MICROPHONE_SWITCH、CAMERA_SWITCH和MUTE_SWITCH这几种控件类型,传入其他控件类型无效。 | 645| status | [PiPControlStatus](#pipcontrolstatus12) | 是 | 表示画中画控制面板控件状态。 | 646 647**错误码:** 648 649以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 650 651| 错误码ID | 错误信息 | 652|-------|-------------------------------------------------------------------------------------------------------------| 653| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 654 655**示例:** 656 657```ts 658let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 659let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // 视频播放控制面板中播放/暂停控件为播放状态。 660pipController.updatePiPControlStatus(controlType, status); 661``` 662 663### setPiPControlEnabled<sup>12+</sup> 664setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 665 666更新控制面板控件使能状态。 667 668**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 669 670**系统能力:** SystemCapability.Window.SessionManager 671 672**参数:** 673 674| 参数名 | 类型 | 必填 | 说明 | 675|-------------|--------|-----|----------------------------------------| 676| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。 | 677| enabled | boolean | 是 | 表示画中画控制面板控件使能状态。true表示控件为可使用状态,false则为禁用状态。 | 678 679**错误码:** 680 681以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 682 683| 错误码ID | 错误信息 | 684|-------|-------------------------------------------------------------------------------------------------------------| 685| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 686 687**示例:** 688 689```ts 690let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 691let enabled: boolean = false; // 视频播放控制面板中播放/暂停控件为禁用状态。 692pipController.setPiPControlEnabled(controlType, enabled); 693``` 694 695### on('stateChange') 696 697on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 698 699开启画中画生命周期状态的监听。 700 701**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 702 703**系统能力:** SystemCapability.Window.SessionManager 704 705**参数:** 706 707| 参数名 | 类型 | 必填 | 说明 | 708|------------|-----------|------|---------------------------------------------------------------------------------------------------| 709| type | string | 是 | 监听事件,固定为'stateChange',即画中画生命周期状态变化事件。 | 710| callback | function | 是 | 回调生命周期状态变化事件以及原因:<br/>state:[PiPState](#pipstate),表示当前画中画生命周期状态;<br/>reason:string,表示当前生命周期的切换原因。 | 711 712**示例:** 713 714```ts 715pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 716 let curState: string = ''; 717 switch (state) { 718 case PiPWindow.PiPState.ABOUT_TO_START: 719 curState = 'ABOUT_TO_START'; 720 break; 721 case PiPWindow.PiPState.STARTED: 722 curState = 'STARTED'; 723 break; 724 case PiPWindow.PiPState.ABOUT_TO_STOP: 725 curState = 'ABOUT_TO_STOP'; 726 break; 727 case PiPWindow.PiPState.STOPPED: 728 curState = 'STOPPED'; 729 break; 730 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 731 curState = 'ABOUT_TO_RESTORE'; 732 break; 733 case PiPWindow.PiPState.ERROR: 734 curState = 'ERROR'; 735 break; 736 default: 737 break; 738 } 739 console.info('stateChange:' + curState + ' reason:' + reason); 740}); 741``` 742 743### off('stateChange') 744 745off(type: 'stateChange'): void 746 747关闭画中画生命周期状态的监听。 748 749**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 750 751**系统能力:** SystemCapability.Window.SessionManager 752 753**参数:** 754 755| 参数名 | 类型 | 必填 | 说明 | 756|-----------|---------------|-------|----------------------------------------| 757| type | string | 是 | 监听事件,固定为'stateChange',即画中画生命周期状态变化事件。 | 758 759**示例:** 760 761```ts 762pipController.off('stateChange'); 763``` 764 765### on('controlPanelActionEvent') 766 767on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 768 769开启画中画控制面板控件动作事件的监听。推荐使用[on('controlEvent')](#oncontrolevent12)来开启画中画控制面板控件动作事件的监听。 770 771**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 772 773**系统能力:** SystemCapability.Window.SessionManager 774 775**参数:** 776 777| 参数名 | 类型 | 必填 | 说明 | 778|----------|------------|-------|---------------------------------------------------| 779| type | string | 是 | 监听事件,固定为'controlPanelActionEvent',即画中画控制面板控件动作事件。 | 780| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | 是 | 描述画中画控制面板控件动作事件回调。 | 781 782**示例:** 783 784```ts 785pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 786 switch (event) { 787 case 'playbackStateChanged': 788 if (status === 0) { 789 //停止视频 790 } else if (status === 1) { 791 //播放视频 792 } 793 break; 794 case 'nextVideo': 795 // 切换到下一个视频 796 break; 797 case 'previousVideo': 798 // 切换到上一个视频 799 break; 800 case 'fastForward': 801 // 视频进度快进 802 break; 803 case 'fastBackward': 804 // 视频进度后退 805 break; 806 default: 807 break; 808 } 809 console.info('registerActionEventCallback, event:' + event); 810}); 811``` 812 813### on('controlEvent')<sup>12+</sup> 814 815on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 816 817开启画中画控制面板控件动作事件的监听。 818 819**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 820 821**系统能力:** SystemCapability.Window.SessionManager 822 823**参数:** 824 825| 参数名 | 类型 | 必填 | 说明 | 826|----------|-----------------------------------------------------|-------|----------------------------------------| 827| type | string | 是 | 监听事件,固定为'controlEvent',即画中画控制面板控件动作事件。 | 828| callback | Callback<[ControlEventParam](#controleventparam12)> | 是 | 描述画中画控制面板控件动作事件回调。 | 829 830**示例:** 831 832```ts 833pipController.on('controlEvent', (control) => { 834 switch (control.controlType) { 835 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 836 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 837 //停止视频 838 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 839 //播放视频 840 } 841 break; 842 case PiPWindow.PiPControlType.VIDEO_NEXT: 843 // 切换到下一个视频 844 break; 845 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 846 // 切换到上一个视频 847 break; 848 case PiPWindow.PiPControlType.FAST_FORWARD: 849 // 视频进度快进 850 break; 851 case PiPWindow.PiPControlType.FAST_BACKWARD: 852 // 视频进度后退 853 break; 854 default: 855 break; 856 } 857 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 858}); 859``` 860 861### off('controlPanelActionEvent') 862 863off(type: 'controlPanelActionEvent'): void 864 865关闭画中画控制面板控件动作事件的监听。推荐使用[off('controlEvent')](#offcontrolevent12)来关闭画中画控制面板控件动作事件的监听。 866 867**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 868 869**系统能力:** SystemCapability.Window.SessionManager 870 871**参数:** 872 873| 参数名 | 类型 | 必填 | 说明 | 874|------------|------------------------------|------|-----------------------------------------------| 875| type | string | 是 | 监听事件,固定为'controlPanelActionEvent',即画中画控制面板控件动作事件。 | 876 877**示例:** 878 879```ts 880pipController.off('controlPanelActionEvent'); 881``` 882 883### off('controlEvent')<sup>12+</sup> 884 885off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 886 887关闭画中画控制面板控件动作事件的监听。 888 889**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 890 891**系统能力:** SystemCapability.Window.SessionManager 892 893**参数:** 894 895| 参数名 | 类型 | 必填 | 说明 | 896|------------|-----------------------------------------------------|----|--------------------------------------------------------| 897| type | string | 是 | 监听事件,固定为'controlEvent',即画中画控制面板控件动作事件。 | 898| callback | Callback<[ControlEventParam](#controleventparam12)> | 否 | 描述画中画控制面板控件动作事件回调。如果不传该参数时,解除type为'controlEvent'的所有回调。 | 899 900**示例:** 901 902```ts 903pipController.off('controlEvent', () => {}); 904```