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#xcomponentcontroller) | 是 | 表示原始[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## PiPWindowSize<sup>15+</sup> 234 235画中画窗口大小。 236 237**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 238 239**系统能力：** SystemCapability.Window.SessionManager 240 241| 名称 | 类型 | 可读 | 可写 | 说明 | 242| ------ | -------- | ---- | ---- | ---------- | 243| width | number | 是 | 否 | 窗口宽度，单位为px，该参数应为正整数，不大于屏幕宽。 | 244| height | number | 是 | 否 | 窗口高度，单位为px，该参数应为正整数，不大于屏幕高。 | 245| scale | number | 是 | 否 | 窗口缩放比，显示大小相对于width和height的缩放比，该参数为浮点数，取值范围大于0.0，小于等于1.0。等于1表示与width和height一样大。 | 246 247## PiPWindowInfo<sup>15+</sup> 248 249画中画窗口信息。 250 251**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 252 253**系统能力：** SystemCapability.Window.SessionManager 254 255| 名称 | 类型 | 可读 | 可写 | 说明 | 256| ------ | -------- | ---- | ---- | ---------- | 257| windowId | number | 是 | 否 | 画中画窗口ID。 | 258| size | [PiPWindowSize](#pipwindowsize15) | 是 | 否 | 画中画窗口大小。 | 259 260## PiPTemplateType 261 262画中画媒体类型枚举。 263 264**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.Window.SessionManager 267 268| 名称 | 值 | 说明 | 269|---------------|-----|--------------------------------------| 270| VIDEO_PLAY | 0 | 表示将要切换为画中画播放的媒体类型是视频，系统依此加载视频播放模板。 | 271| VIDEO_CALL | 1 | 表示将要切换为画中画播放的媒体类型是视频通话，系统依此加载视频通话模板。 | 272| VIDEO_MEETING | 2 | 表示将要切换为画中画播放的媒体类型是视频会议，系统依此加载视频会议模板。 | 273| VIDEO_LIVE | 3 | 表示将要切换为画中画播放的媒体类型是直播，系统依此加载直播模板。 | 274 275## PiPState 276 277画中画生命周期状态枚举。 278 279**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 280 281**系统能力：** SystemCapability.Window.SessionManager 282 283| 名称 | 值 | 说明 | 284|----------------------|-----|-----------------------| 285| ABOUT_TO_START | 1 | 表示画中画将要启动。 | 286| STARTED | 2 | 表示画中画已经启动。 | 287| ABOUT_TO_STOP | 3 | 表示画中画将要停止。 | 288| STOPPED | 4 | 表示画中画已经停止。 | 289| ABOUT_TO_RESTORE | 5 | 表示画中画将从小窗播放恢复到原始播放界面。 | 290| ERROR | 6 | 表示画中画生命周期执行过程出现了异常。 | 291 292## PiPControlGroup<sup>12+</sup> 293 294type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 295 296画中画控制面板的可选控件组列表，应用可以配置是否显示可选控件。默认情况下控制面板只显示基础控件（如视频播放控件组的播放/暂停控件）。 297 298**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 299 300**系统能力：** SystemCapability.Window.SessionManager 301 302| 类型 | 说明 | 303|-------------------------------------------------|-------------| 304| [VideoPlayControlGroup](#videoplaycontrolgroup12) | 视频播放控件组。 | 305| [VideoCallControlGroup](#videocallcontrolgroup12) | 视频通话控件组。 | 306| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | 视频会议控件组。 | 307| [VideoLiveControlGroup](#videolivecontrolgroup12) | 视频直播控件组。 | 308 309 310## VideoPlayControlGroup<sup>12+</sup> 311 312视频播放控件组枚举。仅当[PiPTemplateType](#piptemplatetype)为VIDEO_PLAY时使用。 313 314**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 315 316**系统能力：** SystemCapability.Window.SessionManager 317 318| 名称 | 值 | 说明 | 319|----------------------|-----|-----------------------| 320| VIDEO_PREVIOUS_NEXT | 101 | 视频上一个/下一个控件组。<br/>与视频快进/后退控件组为互斥控件组。如添加视频快进/后退控件组，则不可添加该控件组。 | 321| FAST_FORWARD_BACKWARD | 102 | 视频快进/后退控件组。<br/>与视频上一个/下一个控件组为互斥控件组。如添加视频上一个/下一个控件组，则不可添加该控件组。 | 322 323## VideoCallControlGroup<sup>12+</sup> 324 325视频通话控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_CALL时使用。 326 327**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.Window.SessionManager 330 331| 名称 | 值 | 说明 | 332|----------------------|-----|-----------------------| 333| MICROPHONE_SWITCH | 201 | 打开/关闭麦克风控件组。 | 334| HANG_UP_BUTTON | 202 | 挂断控件组。 | 335| CAMERA_SWITCH | 203 | 打开/关闭摄像头控件组。 | 336| MUTE_SWITCH | 204 | 静音控件组。 | 337 338## VideoMeetingControlGroup<sup>12+</sup> 339 340视频会议控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_MEETING时使用。 341 342**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 343 344**系统能力：** SystemCapability.Window.SessionManager 345 346| 名称 | 值 | 说明 | 347|----------------------|-----|-----------------------| 348| HANG_UP_BUTTON | 301 | 挂断控件组。 | 349| CAMERA_SWITCH | 302 | 打开/关闭摄像头控件组。 | 350| MUTE_SWITCH | 303 | 静音控件组。 | 351| MICROPHONE_SWITCH | 304 | 打开/关闭麦克风控件组。 | 352 353## VideoLiveControlGroup<sup>12+</sup> 354 355视频直播控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_LIVE时使用。 356 357**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 358 359**系统能力：** SystemCapability.Window.SessionManager 360 361| 名称 | 值 | 说明 | 362|----------------------|-----|-----------------------| 363| VIDEO_PLAY_PAUSE | 401 | 播放/暂停直播控件组。 | 364| MUTE_SWITCH | 402 | 静音控件组。 | 365 366## PiPActionEventType 367 368type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 369 370画中画控制面板控件动作事件类型，支持以下四种。 371 372**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 373 374**系统能力：** SystemCapability.Window.SessionManager 375 376| 类型 | 说明 | 377|-------------------------------------------------|-------------| 378| [PiPVideoActionEvent](#pipvideoactionevent) | 视频播放控制面板控件事件类型。 | 379| [PiPCallActionEvent](#pipcallactionevent) | 视频通话控制面板控件事件类型。 | 380| [PiPMeetingActionEvent](#pipmeetingactionevent) | 视频会议控制面板控件事件类型。 | 381| [PiPLiveActionEvent](#pipliveactionevent) | 直播控制面板控件事件类型。 | 382 383## PiPVideoActionEvent 384 385type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 386 387视频播放控制事件类型。 388 389**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 390 391**系统能力：** SystemCapability.Window.SessionManager 392 393| 类型 | 说明 | 394| ---------------------------- | ----------------------------------------- | 395| 'playbackStateChanged' | 播放状态发生了变化。 | 396| 'nextVideo' | 播放下一个视频。 | 397| 'previousVideo' | 播放上一个视频。 | 398| 'fastForward'<sup>12+</sup> | 视频进度快进。从API version 12 开始支持。 | 399| 'fastBackward'<sup>12+</sup> | 视频进度后退。从API version 12 开始支持。 | 400 401## PiPCallActionEvent 402 403type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 404 405视频通话控制事件类型。 406 407**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 408 409**系统能力：** SystemCapability.Window.SessionManager 410 411| 类型 | 说明 | 412| ------------------- | ------------------ | 413| 'hangUp' | 挂断视频通话。 | 414| 'micStateChanged' | 打开或关闭麦克风。 | 415| 'videoStateChanged' | 打开或关闭摄像头。 | 416| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 417 418 419## PiPMeetingActionEvent 420 421type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 422 423视频会议控制事件类型。 424 425**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 426 427**系统能力：** SystemCapability.Window.SessionManager 428 429| 类型 | 说明 | 430| ------------------- | ------------------ | 431| 'hangUp' | 挂断视频会议。 | 432| 'voiceStateChanged' | 静音或解除静音。 | 433| 'videoStateChanged' | 打开或关闭摄像头。 | 434| 'micStateChanged'<sup>12+</sup> | 打开或关闭麦克风。 | 435 436 437## PiPLiveActionEvent 438 439type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 440 441直播控制事件类型。 442 443**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 444 445**系统能力：** SystemCapability.Window.SessionManager 446 447| 类型 | 说明 | 448| ---------------------- | ---------------- | 449| 'playbackStateChanged' | 播放或暂停直播。 | 450| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 451 452 453## PiPControlStatus<sup>12+</sup> 454 455控制面板控件状态枚举。 456 457**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 458 459**系统能力：** SystemCapability.Window.SessionManager 460 461| 名称 | 值 | 说明 | 462|----------------------|-----|-----------------------| 463| PLAY | 1 | 播放。 | 464| PAUSE | 0 | 暂停。 | 465| OPEN | 1 | 打开。 | 466| CLOSE | 0 | 关闭。 | 467 468## PiPControlType<sup>12+</sup> 469 470控制面板控件类型枚举。 471 472**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 473 474**系统能力：** SystemCapability.Window.SessionManager 475 476| 名称 | 值 | 说明 | 477|-------------------|-----|--------------------------------------| 478| VIDEO_PLAY_PAUSE | 0 | 播放/暂停控件。 | 479| VIDEO_PREVIOUS | 1 | 视频上一个控件。 | 480| VIDEO_NEXT | 2 | 视频下一个控件。 | 481| FAST_FORWARD | 3 | 视频快进控件 | 482| FAST_BACKWARD | 4 | 视频快退控件。 | 483| HANG_UP_BUTTON | 5 | 挂断控件。 | 484| MICROPHONE_SWITCH | 6 | 打开/关闭麦克风控件。 | 485| CAMERA_SWITCH | 7 | 打开/关闭摄像头控件。 | 486| MUTE_SWITCH | 8 | 打开/关闭静音控件。 | 487 488 489## ControlPanelActionEventCallback<sup>12+</sup> 490 491type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 492 493描述画中画控制面板控件动作事件回调。 494 495**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 496 497**系统能力：** SystemCapability.Window.SessionManager 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502|--------------------------|--------------|--------------|-----------------------------------| 503| event | [PiPActionEventType](#pipactioneventtype) | 是 | 回调画中画控制面板控件动作事件类型。<br/>应用依据控件动作事件做相应处理，如触发'playbackStateChanged'事件时，需要开始或停止视频。 | 504| status | number | 否 | 表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为1，关闭为0。其余控件该参数返回默认值-1。 | 505 506## ControlEventParam<sup>12+</sup> 507 508画中画控制面板控件动作回调的参数。 509 510**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 511 512**系统能力：** SystemCapability.Window.SessionManager 513 514| 名称 | 类型 | 必填 | 说明 | 515|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 516| controlType | [PiPControlType](#pipcontroltype12) | 是 | 回调画中画控制面板控件动作事件类型。应用依据控件类型做相应处理，如视频模板中暂停/播放控件被点击时，需要开始或停止视频。 | 517| status | [PiPControlStatus](#pipcontrolstatus12) | 否 | 表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为PiPControlStatus.PLAY，关闭为PiPControlStatus.PAUSE。如不具备开/关和播放/暂停状态的挂断控件默认返回值为-1。 | 518 519## PiPController 520 521画中画控制器实例。用于启动、停止画中画以及更新回调注册等。 522 523下列API示例中都需先使用[PiPWindow.create()](#pipwindowcreate)方法获取到PiPController实例，再通过此实例调用对应方法。 524 525**系统能力：** SystemCapability.Window.SessionManager 526 527### startPiP 528 529startPiP(): Promise<void> 530 531启动画中画，使用Promise异步回调。 532 533**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 534 535**系统能力：** SystemCapability.Window.SessionManager 536 537**返回值：** 538 539| 类型 | 说明 | 540|------------------------|--------------------| 541| Promise<void> | 无返回结果的Promise对象。 | 542 543**错误码：** 544 545以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 546 547| 错误码ID | 错误信息 | 548|------------|--------------------------------------------------------| 549| 1300012 | The PiP window state is abnormal. | 550| 1300013 | Failed to create the PiP window. | 551| 1300014 | PiP internal error. | 552| 1300015 | Repeated PiP operation. | 553 554**示例：** 555 556```ts 557let promise : Promise<void> = pipController.startPiP(); 558promise.then(() => { 559 console.info(`Succeeded in starting pip.`); 560}).catch((err: BusinessError) => { 561 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 562}); 563``` 564 565### stopPiP 566 567stopPiP(): Promise<void> 568 569停止画中画，使用Promise异步回调。 570 571**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 572 573**系统能力：** SystemCapability.Window.SessionManager 574 575**返回值：** 576 577| 类型 | 说明 | 578|----------------------|---------------------| 579| Promise<void> | 无返回结果的Promise对象。 | 580 581**错误码：** 582 583以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 584 585| 错误码ID | 错误信息 | 586|---------|-----------------------------------| 587| 1300011 | Failed to destroy the PiP window. | 588| 1300012 | The PiP window state is abnormal. | 589| 1300015 | Repeated PiP operation. | 590 591**示例：** 592 593```ts 594let promise : Promise<void> = pipController.stopPiP(); 595promise.then(() => { 596 console.info(`Succeeded in stopping pip.`); 597}).catch((err: BusinessError) => { 598 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 599}); 600``` 601 602### setAutoStartEnabled 603 604setAutoStartEnabled(enable: boolean): void 605 606设置是否需要在返回桌面时自动启动画中画。 607 608**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 609 610**系统能力：** SystemCapability.Window.SessionManager 611 612**参数：** 613 614| 参数名 | 类型 | 必填 | 说明 | 615|----------|-----------|-------|---------------------------------| 616| enable | boolean | 是 | 如返回桌面时需自动启动画中画，则该参数配置为true，否则为false。若设置中自动启动画中画开关为关闭状态，就算该参数配置为true，应用返回桌面时也不会自动启动画中画窗口。 | 617 618**示例：** 619 620```ts 621let enable: boolean = true; 622pipController.setAutoStartEnabled(enable); 623``` 624 625### updateContentSize 626 627updateContentSize(width: number, height: number): void 628 629当媒体源切换时，向画中画控制器更新媒体源尺寸信息。 630 631**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 632 633**系统能力：** SystemCapability.Window.SessionManager 634 635**参数：** 636 637| 参数名 | 类型 | 必填 | 说明 | 638|--------|--------|-----|----------------------------------------| 639| width | number | 是 | 表示媒体内容宽度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。 | 640| height | number | 是 | 表示媒体内容高度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。 | 641 642**错误码：** 643 644以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 645 646| 错误码ID | 错误信息 | 647|-------|-------------------------------------------------------------------------------------------------------------| 648| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 649 650**示例：** 651 652```ts 653let width: number = 540; // 假设当前内容宽度变为540px。 654let height: number = 960; // 假设当前内容高度变为960px。 655pipController.updateContentSize(width, height); 656``` 657 658### updatePiPControlStatus<sup>12+</sup> 659updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 660 661更新控制面板控件功能状态。 662 663**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 664 665**系统能力：** SystemCapability.Window.SessionManager 666 667**参数：** 668 669| 参数名 | 类型 | 必填 | 说明 | 670|--------|--------|-----|----------------------------------------------------------------------------------------------------| 671| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。目前仅支持VIDEO_PLAY_PAUSE、MICROPHONE_SWITCH、CAMERA_SWITCH和MUTE_SWITCH这几种控件类型，传入其他控件类型无效。 | 672| status | [PiPControlStatus](#pipcontrolstatus12) | 是 | 表示画中画控制面板控件状态。 | 673 674**错误码：** 675 676以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 677 678| 错误码ID | 错误信息 | 679|-------|-------------------------------------------------------------------------------------------------------------| 680| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 681 682**示例：** 683 684```ts 685let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 686let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // 视频播放控制面板中播放/暂停控件为播放状态。 687pipController.updatePiPControlStatus(controlType, status); 688``` 689 690### setPiPControlEnabled<sup>12+</sup> 691setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 692 693更新控制面板控件使能状态。 694 695**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 696 697**系统能力：** SystemCapability.Window.SessionManager 698 699**参数：** 700 701| 参数名 | 类型 | 必填 | 说明 | 702|-------------|--------|-----|----------------------------------------| 703| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。 | 704| enabled | boolean | 是 | 表示画中画控制面板控件使能状态。true表示控件为可使用状态，false则为禁用状态。 | 705 706**错误码：** 707 708以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 709 710| 错误码ID | 错误信息 | 711|-------|-------------------------------------------------------------------------------------------------------------| 712| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 713 714**示例：** 715 716```ts 717let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 718let enabled: boolean = false; // 视频播放控制面板中播放/暂停控件为禁用状态。 719pipController.setPiPControlEnabled(controlType, enabled); 720``` 721### getPiPWindowInfo<sup>15+</sup> 722getPiPWindowInfo(): Promise<[PiPWindowInfo](#pipwindowinfo15)> 723 724获取画中画窗口信息。 725 726**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 727 728**系统能力：** SystemCapability.Window.SessionManager 729 730**返回值：** 731 732| 类型 | 说明 | 733|----------------------|---------------------| 734| Promise<[PiPWindowInfo](#pipwindowinfo15)> | Promise对象，返回当前画中画窗口信息。 | 735 736**错误码：** 737 738以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 739 740| 错误码ID | 错误信息 | 741|-------|-------------------------------------------------------------------------------------------------------------| 742| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 743| 1300014 | PiP internal error. | 744 745**示例：** 746 747```ts 748let pipWindowInfo: PiPWindow.PiPWindowInfo | undefined = undefined; 749try { 750 let promise : Promise<PiPWindow.PiPWindowInfo> = pipController.getPiPWindowInfo(); 751 promise.then((data) => { 752 pipWindowInfo = data; 753 console.info('Success in get pip window info. Info: ' + JSON.stringify(data)); 754 }).catch((err: BusinessError) => { 755 console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`); 756 }); 757} catch (exception) { 758 console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`); 759} 760``` 761 762### on('stateChange') 763 764on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 765 766开启画中画生命周期状态的监听。 767 768**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 769 770**系统能力：** SystemCapability.Window.SessionManager 771 772**参数：** 773 774| 参数名 | 类型 | 必填 | 说明 | 775|------------|-----------|------|---------------------------------------------------------------------------------------------------| 776| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 777| callback | function | 是 | 回调生命周期状态变化事件以及原因。<br/>state：[PiPState](#pipstate)，表示当前画中画生命周期状态。<br/>reason：string，表示当前生命周期的切换原因。 | 778 779**示例：** 780 781```ts 782pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 783 let curState: string = ''; 784 switch (state) { 785 case PiPWindow.PiPState.ABOUT_TO_START: 786 curState = 'ABOUT_TO_START'; 787 break; 788 case PiPWindow.PiPState.STARTED: 789 curState = 'STARTED'; 790 break; 791 case PiPWindow.PiPState.ABOUT_TO_STOP: 792 curState = 'ABOUT_TO_STOP'; 793 break; 794 case PiPWindow.PiPState.STOPPED: 795 curState = 'STOPPED'; 796 break; 797 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 798 curState = 'ABOUT_TO_RESTORE'; 799 break; 800 case PiPWindow.PiPState.ERROR: 801 curState = 'ERROR'; 802 break; 803 default: 804 break; 805 } 806 console.info('stateChange:' + curState + ' reason:' + reason); 807}); 808``` 809 810### off('stateChange') 811 812off(type: 'stateChange'): void 813 814关闭画中画生命周期状态的监听。 815 816**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 817 818**系统能力：** SystemCapability.Window.SessionManager 819 820**参数：** 821 822| 参数名 | 类型 | 必填 | 说明 | 823|-----------|---------------|-------|----------------------------------------| 824| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 825 826**示例：** 827 828```ts 829pipController.off('stateChange'); 830``` 831 832### on('controlPanelActionEvent') 833 834on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 835 836开启画中画控制面板控件动作事件的监听。推荐使用[on('controlEvent')](#oncontrolevent12)来开启画中画控制面板控件动作事件的监听。 837 838**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 839 840**系统能力：** SystemCapability.Window.SessionManager 841 842**参数：** 843 844| 参数名 | 类型 | 必填 | 说明 | 845|----------|------------|-------|---------------------------------------------------| 846| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。 | 847| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | 是 | 描述画中画控制面板控件动作事件回调。 | 848 849**示例：** 850 851```ts 852pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 853 switch (event) { 854 case 'playbackStateChanged': 855 if (status === 0) { 856 //停止视频 857 } else if (status === 1) { 858 //播放视频 859 } 860 break; 861 case 'nextVideo': 862 // 切换到下一个视频 863 break; 864 case 'previousVideo': 865 // 切换到上一个视频 866 break; 867 case 'fastForward': 868 // 视频进度快进 869 break; 870 case 'fastBackward': 871 // 视频进度后退 872 break; 873 default: 874 break; 875 } 876 console.info('registerActionEventCallback, event:' + event); 877}); 878``` 879 880### on('controlEvent')<sup>12+</sup> 881 882on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 883 884开启画中画控制面板控件动作事件的监听。 885 886**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 887 888**系统能力：** SystemCapability.Window.SessionManager 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893|----------|-----------------------------------------------------|-------|----------------------------------------| 894| type | string | 是 | 监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。 | 895| callback | Callback<[ControlEventParam](#controleventparam12)> | 是 | 描述画中画控制面板控件动作事件回调。 | 896 897**示例：** 898 899```ts 900pipController.on('controlEvent', (control) => { 901 switch (control.controlType) { 902 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 903 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 904 //停止视频 905 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 906 //播放视频 907 } 908 break; 909 case PiPWindow.PiPControlType.VIDEO_NEXT: 910 // 切换到下一个视频 911 break; 912 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 913 // 切换到上一个视频 914 break; 915 case PiPWindow.PiPControlType.FAST_FORWARD: 916 // 视频进度快进 917 break; 918 case PiPWindow.PiPControlType.FAST_BACKWARD: 919 // 视频进度后退 920 break; 921 default: 922 break; 923 } 924 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 925}); 926``` 927 928### off('controlPanelActionEvent') 929 930off(type: 'controlPanelActionEvent'): void 931 932关闭画中画控制面板控件动作事件的监听。推荐使用[off('controlEvent')](#offcontrolevent12)来关闭画中画控制面板控件动作事件的监听。 933 934**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 935 936**系统能力：** SystemCapability.Window.SessionManager 937 938**参数：** 939 940| 参数名 | 类型 | 必填 | 说明 | 941|------------|------------------------------|------|-----------------------------------------------| 942| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。 | 943 944**示例：** 945 946```ts 947pipController.off('controlPanelActionEvent'); 948``` 949 950### off('controlEvent')<sup>12+</sup> 951 952off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 953 954关闭画中画控制面板控件动作事件的监听。 955 956**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 957 958**系统能力：** SystemCapability.Window.SessionManager 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963|------------|-----------------------------------------------------|----|--------------------------------------------------------| 964| type | string | 是 | 监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。 | 965| callback | Callback<[ControlEventParam](#controleventparam12)> | 否 | 描述画中画控制面板控件动作事件回调。如果不传该参数时，解除type为'controlEvent'的所有回调。 | 966 967**示例：** 968 969```ts 970pipController.off('controlEvent', () => {}); 971``` 972 973### on('pipWindowSizeChange')<sup>15+</sup> 974 975on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void 976 977开启画中画窗口尺寸变化事件的监听。 978 979**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 980 981**系统能力：** SystemCapability.Window.SessionManager 982 983**参数：** 984 985| 参数名 | 类型 | 必填 | 说明 | 986|----------|---------------------------------------------|-------|---------------------------------------------------| 987| type | string | 是 | 监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。 | 988| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | 是 | 回调函数。返回当前画中画窗口的尺寸。 | 989 990**错误码：** 991 992以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 993 994| 错误码ID | 错误信息 | 995| ------- | -------------------------------------------- | 996| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 997| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 998| 1300014 | PiP internal error. | 999 1000**示例：** 1001 1002```ts 1003try { 1004 pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => { 1005 console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size)); 1006 }); 1007} catch (exception) { 1008 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1009} 1010``` 1011 1012### off('pipWindowSizeChange')<sup>15+</sup> 1013 1014off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void 1015 1016关闭画中画窗口尺寸变化事件的监听。 1017 1018**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1019 1020**系统能力：** SystemCapability.Window.SessionManager 1021 1022**参数：** 1023 1024| 参数名 | 类型 | 必填 | 说明 | 1025|----------|------------|----|---------------------------------------------------------------------| 1026| type | string | 是 | 监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。 | 1027| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | 否 | 回调函数。返回当前画中画窗口的尺寸。如果传入参数，则关闭该监听。如果未传入参数，解除type为'pipWindowSizeChange'的所有回调。 | 1028 1029**错误码：** 1030 1031以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1032 1033| 错误码ID | 错误信息 | 1034| ------- | -------------------------------------------- | 1035| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1036| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1037| 1300014 | PiP internal error. | 1038 1039**示例：** 1040 1041```ts 1042const callback = (size: PiPWindow.PiPWindowSize) => { 1043 // ... 1044} 1045try { 1046 // 通过on接口开启监听 1047 pipController.on('pipWindowSizeChange', callback); 1048} catch (exception) { 1049 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1050} 1051 1052try { 1053 // 关闭指定callback的监听 1054 pipController.off('pipWindowSizeChange', callback); 1055 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 1056 pipController.off('pipWindowSizeChange'); 1057} catch (exception) { 1058 console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1059} 1060```