1# @ohos.PiPWindow (画中画窗口) 2 3该模块提供画中画基础功能，包括判断当前系统是否支持画中画功能，以及创建画中画控制器用于启动或停止画中画等。适用于视频播放、视频通话或视频会议场景下，以小窗（画中画）模式呈现内容。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 在API version 20之前，支持在Phone、Tablet设备使用画中画功能，其他设备不可用；从API version 20开始，支持在Phone、PC/2in1、Tablet设备使用画中画功能，其他设备不可用。 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, UIContext } from '@kit.ArkUI'; 76import { common } from '@kit.AbilityKit'; 77 78class Params { 79 text: string = ''; 80 constructor(text: string) { 81 this.text = text; 82 } 83} 84 85// 开发者可以通过@Builder装饰器实现布局构建 86@Builder 87function buildText(params: Params) { 88 Column() { 89 Text(params.text) 90 .fontSize(20) 91 .fontColor(Color.Red) 92 } 93 .width('100%') // 宽度方向充满画中画窗口 94 .height('100%') // 高度方向充满画中画窗口 95} 96 97// 开发者可通过继承NodeController实现自定义UI控制器 98class TextNodeController extends NodeController { 99 private message: string; 100 private textNode: BuilderNode<[Params]> | null = null; 101 constructor(message: string) { 102 super(); 103 this.message = message; 104 } 105 106 // 通过BuilderNode加载自定义布局 107 makeNode(context: UIContext): FrameNode | null { 108 this.textNode = new BuilderNode(context); 109 this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message)); 110 return this.textNode.getFrameNode(); 111 } 112 113 // 开发者可自定义该方法实现布局更新 114 update(message: string) { 115 console.log(`update message: ${message}`); 116 if (this.textNode !== null) { 117 this.textNode.update(new Params(message)); 118 } 119 } 120} 121 122@Entry 123@Component 124struct Index { 125 private message: string = 'createPiP'; 126 private pipController: PiPWindow.PiPController | undefined = undefined; 127 private mXComponentController: XComponentController = new XComponentController(); // 开发者应使用该mXComponentController初始化XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} )，保证XComponent的内容可以被迁移到画中画窗口。 128 private nodeController: TextNodeController = new TextNodeController('this is custom UI'); 129 private navId: string = "page_1"; // 假设当前页面的导航id为page_1，详见PiPConfiguration定义，具体导航名称由开发者自行定义。 130 private contentWidth: number = 800; // 假设当前内容宽度800px。 131 private contentHeight: number = 600; // 假设当前内容高度600px。 132 private para: Record<string, number> = { 'PropA': 47 }; 133 private localStorage: LocalStorage = new LocalStorage(this.para); 134 private res: boolean = this.localStorage.setOrCreate('PropB', 121); 135 private defaultWindowSizeType: number = 1; // 指定画中画第一次拉起窗口为小窗口。 136 private config: PiPWindow.PiPConfiguration = { 137 context: this.getUIContext().getHostContext() as Context, 138 componentController: this.mXComponentController, 139 navigationId: this.navId, 140 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 141 contentWidth: this.contentWidth, 142 contentHeight: this.contentHeight, 143 controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], 144 customUIController: this.nodeController, // 可选，如果需要在画中画显示内容上方展示自定义UI，可设置该参数。 145 localStorage: this.localStorage, // 可选，如果需要跟踪主窗实例，可设置此参数。 146 defaultWindowSizeType: this.defaultWindowSizeType, // 可选，如果需要配置默认启动窗口档位，可设置此参数。 147 }; 148 149 createPiP() { 150 let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(this.config); 151 promise.then((data: PiPWindow.PiPController) => { 152 this.pipController = data; 153 console.info(`Succeeded in creating pip controller. Data:${data}`); 154 }).catch((err: BusinessError) => { 155 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 156 }); 157 } 158 159 //仅用于功能测试，实际开发过程中开发者按功能需求设计组件 160 build() { 161 RelativeContainer() { 162 Button(this.message) 163 .onClick(() => { 164 this.createPiP(); 165 }) 166 } 167 } 168} 169``` 170 171## PiPWindow.create<sup>12+</sup> 172 173create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise<PiPController> 174 175通过typeNode创建画中画控制器，使用Promise异步回调。 176 177**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.Window.SessionManager 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 185| config | [PiPConfiguration](#pipconfiguration) | 是 | 创建画中画控制器的参数。该参数不能为空，并且构造该参数的context不能为空。构造该参数时，如果指定了templateType，需保证templateType是[PiPTemplateType](#piptemplatetype)类型；如果指定了controlGroups，需保证controlGroups与templateType匹配，详见[PiPControlGroup](#pipcontrolgroup12)。 | 186| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | 是 | 用于渲染画中画窗口中的内容。该参数不能为空。| 187 188**返回值：** 189 190| 类型 | 说明 | 191|------------------------------------------------------------|--------------------------| 192| Promise<[PiPController](#pipcontroller)> | Promise对象。返回当前创建的画中画控制器。 | 193 194**错误码：** 195 196以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 197 198| 错误码ID | 错误信息 | 199|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 200| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 201| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 202 203**示例：** 204 205```ts 206import { BusinessError } from '@kit.BasicServicesKit'; 207import { PiPWindow, typeNode, UIContext } from '@kit.ArkUI'; 208import { common } from '@kit.AbilityKit'; 209 210@Entry 211@Component 212struct Index { 213 private message = 'createPiP' 214 private pipController: PiPWindow.PiPController | undefined = undefined; 215 private xComponentController: XComponentController = new XComponentController(); 216 private context: UIContext | undefined = this.getUIContext(); // 可传入UIContext或在布局中通过this.getUIContext()为context赋有效值 217 private contentWidth: number = 800; // 假设当前内容宽度800px。 218 private contentHeight: number = 600; // 假设当前内容高度600px。 219 private config: PiPWindow.PiPConfiguration = { 220 context: this.getUIContext().getHostContext() as Context, 221 componentController: this.xComponentController, 222 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 223 contentWidth: this.contentWidth, 224 contentHeight: this.contentHeight, 225 }; 226 private options: XComponentOptions = { 227 type: XComponentType.SURFACE, 228 controller: this.xComponentController 229 } 230 private xComponent = typeNode.createNode(this.context, 'XComponent', this.options); 231 232 createPiP() { 233 let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(this.config, this.xComponent); 234 promise.then((data: PiPWindow.PiPController) => { 235 this.pipController = data; 236 console.info(`Succeeded in creating pip controller. Data:${data}`); 237 }).catch((err: BusinessError) => { 238 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 239 }); 240 } 241 242 //仅用于功能测试，实际开发过程中开发者按功能需求设计组件 243 build() { 244 RelativeContainer() { 245 Button(this.message) 246 .onClick(() => { 247 this.createPiP(); 248 }) 249 } 250 } 251} 252``` 253 254## PiPConfiguration 255 256创建画中画控制器时的参数。 257 258**系统能力：** SystemCapability.Window.SessionManager 259 260| 名称 | 类型 | 必填 | 说明 | 261|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 262| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 表示上下文环境。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 263| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md#xcomponentcontroller) | 是 | 表示原始[XComponent](arkui-ts/ts-basic-components-xcomponent.md)控制器。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 264| 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，还原场景下也能够从画中画窗口恢复到原页面。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 265| templateType | [PiPTemplateType](#piptemplatetype) | 否 | 模板类型，用以区分视频播放、视频通话或视频会议，不传值则默认为视频播放模板。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 266| contentWidth | number | 否 | 原始内容宽度，单位为px。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时，不传值则默认为1920。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时，不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的宽度。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 267| contentHeight | number | 否 | 原始内容高度，单位为px。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时，不传值则默认为1080。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时，不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的高度。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 268| controlGroups<sup>12+</sup> | Array<[PiPControlGroup](#pipcontrolgroup12)> | 否 | 画中画控制面板的可选控件组列表，应用可以对此进行配置以决定是否显示。应用未配置时，面板显示基础控件（如视频播放控件组的播放/暂停控件）；应用选择配置时，则最多可以选择三个控件。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 269| customUIController<sup>12+</sup> | [NodeController](js-apis-arkui-nodeController.md) | 否 | 用于实现在画中画界面内容上方展示自定义UI功能，不传值则默认不使用自定义UI功能。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 270| localStorage<sup>17+</sup> | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 否 | 页面级别的UI状态存储单元。多实例下可用来跟踪主窗实例的UI状态存储对象，不传值则无法通过画中画窗口获取主窗的UI状态存储对象。<br/>**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 | 271| defaultWindowSizeType<sup>19+</sup>| number | 否 | 应用第一次拉起画中画的窗口大小。<br/>0：代表不设置大小。按照上次画中画关闭前的大小启动；<br/>1：代表小窗；<br/>2：代表大窗；<br/>不传值则为默认值0。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 272 273## PiPWindowSize<sup>15+</sup> 274 275画中画窗口大小。 276 277**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 278 279**系统能力：** SystemCapability.Window.SessionManager 280 281| 名称 | 类型 | 只读 | 可选 | 说明 | 282| ------ | -------- | ---- | ---- | ---------- | 283| width | number | 是 | 否 | 窗口宽度，单位为px，该参数应为正整数，不大于屏幕宽。 | 284| height | number | 是 | 否 | 窗口高度，单位为px，该参数应为正整数，不大于屏幕高。 | 285| scale | number | 是 | 否 | 窗口缩放比，显示大小相对于width和height的缩放比，该参数为浮点数，取值范围大于0.0，小于等于1.0。等于1表示与width和height一样大。 | 286 287## PiPWindowInfo<sup>15+</sup> 288 289画中画窗口信息。 290 291**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 292 293**系统能力：** SystemCapability.Window.SessionManager 294 295| 名称 | 类型 | 只读 | 可选 | 说明 | 296| ------ | -------- | ---- | ---- | ---------- | 297| windowId | number | 是 | 否 | 画中画窗口ID。 | 298| size | [PiPWindowSize](#pipwindowsize15) | 是 | 否 | 画中画窗口大小。 | 299 300## PiPTemplateType 301 302画中画媒体类型枚举。 303 304**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 305 306**系统能力：** SystemCapability.Window.SessionManager 307 308| 名称 | 值 | 说明 | 309|---------------|-----|--------------------------------------| 310| VIDEO_PLAY | 0 | 表示将要切换为画中画播放的媒体类型是视频，系统依此加载视频播放模板。 | 311| VIDEO_CALL | 1 | 表示将要切换为画中画播放的媒体类型是视频通话，系统依此加载视频通话模板。 | 312| VIDEO_MEETING | 2 | 表示将要切换为画中画播放的媒体类型是视频会议，系统依此加载视频会议模板。 | 313| VIDEO_LIVE | 3 | 表示将要切换为画中画播放的媒体类型是直播，系统依此加载直播模板。 | 314 315## PiPState 316 317画中画生命周期状态枚举。 318 319**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 320 321**系统能力：** SystemCapability.Window.SessionManager 322 323| 名称 | 值 | 说明 | 324|----------------------|-----|-----------------------| 325| ABOUT_TO_START | 1 | 表示画中画将要启动。 | 326| STARTED | 2 | 表示画中画已经启动。 | 327| ABOUT_TO_STOP | 3 | 表示画中画将要停止。 | 328| STOPPED | 4 | 表示画中画已经停止。 | 329| ABOUT_TO_RESTORE | 5 | 表示画中画将从小窗播放恢复到原始播放界面。 | 330| ERROR | 6 | 表示画中画生命周期执行过程出现了异常。 | 331 332## PiPControlGroup<sup>12+</sup> 333 334type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 335 336画中画控制面板的可选控件组列表，应用可以配置是否显示可选控件。默认情况下控制面板只显示基础控件（如视频播放控件组的播放/暂停控件）。 337 338**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 339 340**系统能力：** SystemCapability.Window.SessionManager 341 342| 类型 | 说明 | 343|-------------------------------------------------|-------------| 344| [VideoPlayControlGroup](#videoplaycontrolgroup12) | 视频播放控件组。 | 345| [VideoCallControlGroup](#videocallcontrolgroup12) | 视频通话控件组。 | 346| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | 视频会议控件组。 | 347| [VideoLiveControlGroup](#videolivecontrolgroup12) | 视频直播控件组。 | 348 349 350## VideoPlayControlGroup<sup>12+</sup> 351 352视频播放控件组枚举。仅当[PiPTemplateType](#piptemplatetype)为VIDEO_PLAY时使用。 353 354**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 355 356**系统能力：** SystemCapability.Window.SessionManager 357 358| 名称 | 值 | 说明 | 359|----------------------|-----|-----------------------| 360| VIDEO_PREVIOUS_NEXT | 101 | 视频上一个/下一个控件组。<br/>与视频快进/后退控件组为互斥控件组。如添加视频快进/后退控件组，则不可添加该控件组。 | 361| FAST_FORWARD_BACKWARD | 102 | 视频快进/后退控件组。<br/>与视频上一个/下一个控件组为互斥控件组。如添加视频上一个/下一个控件组，则不可添加该控件组。 | 362 363## VideoCallControlGroup<sup>12+</sup> 364 365视频通话控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_CALL时使用。 366 367**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 368 369**系统能力：** SystemCapability.Window.SessionManager 370 371| 名称 | 值 | 说明 | 372|----------------------|-----|-----------------------| 373| MICROPHONE_SWITCH | 201 | 打开/关闭麦克风控件组。 | 374| HANG_UP_BUTTON | 202 | 挂断控件组。 | 375| CAMERA_SWITCH | 203 | 打开/关闭摄像头控件组。 | 376| MUTE_SWITCH | 204 | 静音控件组。 | 377 378## VideoMeetingControlGroup<sup>12+</sup> 379 380视频会议控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_MEETING时使用。 381 382**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 383 384**系统能力：** SystemCapability.Window.SessionManager 385 386| 名称 | 值 | 说明 | 387|----------------------|-----|-----------------------| 388| HANG_UP_BUTTON | 301 | 挂断控件组。 | 389| CAMERA_SWITCH | 302 | 打开/关闭摄像头控件组。 | 390| MUTE_SWITCH | 303 | 静音控件组。 | 391| MICROPHONE_SWITCH | 304 | 打开/关闭麦克风控件组。 | 392 393## VideoLiveControlGroup<sup>12+</sup> 394 395视频直播控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_LIVE时使用。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.Window.SessionManager 400 401| 名称 | 值 | 说明 | 402|----------------------|-----|-----------------------| 403| VIDEO_PLAY_PAUSE | 401 | 播放/暂停直播控件组。 | 404| MUTE_SWITCH | 402 | 静音控件组。 | 405 406## PiPActionEventType 407 408type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 409 410画中画控制面板控件动作事件类型，支持以下四种。 411 412**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 413 414**系统能力：** SystemCapability.Window.SessionManager 415 416| 类型 | 说明 | 417|-------------------------------------------------|-------------| 418| [PiPVideoActionEvent](#pipvideoactionevent) | 视频播放控制面板控件事件类型。 | 419| [PiPCallActionEvent](#pipcallactionevent) | 视频通话控制面板控件事件类型。 | 420| [PiPMeetingActionEvent](#pipmeetingactionevent) | 视频会议控制面板控件事件类型。 | 421| [PiPLiveActionEvent](#pipliveactionevent) | 直播控制面板控件事件类型。 | 422 423## PiPVideoActionEvent 424 425type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 426 427视频播放控制事件类型。 428 429**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 430 431**系统能力：** SystemCapability.Window.SessionManager 432 433| 类型 | 说明 | 434| ---------------------------- | ----------------------------------------- | 435| 'playbackStateChanged' | 播放状态发生了变化。 | 436| 'nextVideo' | 播放下一个视频。 | 437| 'previousVideo' | 播放上一个视频。 | 438| 'fastForward'<sup>12+</sup> | 视频进度快进。从API version 12 开始支持。 | 439| 'fastBackward'<sup>12+</sup> | 视频进度后退。从API version 12 开始支持。 | 440 441## PiPCallActionEvent 442 443type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 444 445视频通话控制事件类型。 446 447**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 448 449**系统能力：** SystemCapability.Window.SessionManager 450 451| 类型 | 说明 | 452| ------------------- | ------------------ | 453| 'hangUp' | 挂断视频通话。 | 454| 'micStateChanged' | 打开或关闭麦克风。 | 455| 'videoStateChanged' | 打开或关闭摄像头。 | 456| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 457 458 459## PiPMeetingActionEvent 460 461type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 462 463视频会议控制事件类型。 464 465**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 466 467**系统能力：** SystemCapability.Window.SessionManager 468 469| 类型 | 说明 | 470| ------------------- | ------------------ | 471| 'hangUp' | 挂断视频会议。 | 472| 'voiceStateChanged' | 静音或解除静音。 | 473| 'videoStateChanged' | 打开或关闭摄像头。 | 474| 'micStateChanged'<sup>12+</sup> | 打开或关闭麦克风。 | 475 476 477## PiPLiveActionEvent 478 479type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 480 481直播控制事件类型。 482 483**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 484 485**系统能力：** SystemCapability.Window.SessionManager 486 487| 类型 | 说明 | 488| ---------------------- | ---------------- | 489| 'playbackStateChanged' | 播放或暂停直播。 | 490| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。 | 491 492 493## PiPControlStatus<sup>12+</sup> 494 495控制面板控件状态枚举。 496 497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 498 499**系统能力：** SystemCapability.Window.SessionManager 500 501| 名称 | 值 | 说明 | 502|----------------------|-----|-----------------------| 503| PLAY | 1 | 播放。 | 504| PAUSE | 0 | 暂停。 | 505| OPEN | 1 | 打开。 | 506| CLOSE | 0 | 关闭。 | 507 508## PiPControlType<sup>12+</sup> 509 510控制面板控件类型枚举。 511 512**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 513 514**系统能力：** SystemCapability.Window.SessionManager 515 516| 名称 | 值 | 说明 | 517|-------------------|-----|--------------------------------------| 518| VIDEO_PLAY_PAUSE | 0 | 播放/暂停控件。 | 519| VIDEO_PREVIOUS | 1 | 视频上一个控件。 | 520| VIDEO_NEXT | 2 | 视频下一个控件。 | 521| FAST_FORWARD | 3 | 视频快进控件 | 522| FAST_BACKWARD | 4 | 视频快退控件。 | 523| HANG_UP_BUTTON | 5 | 挂断控件。 | 524| MICROPHONE_SWITCH | 6 | 打开/关闭麦克风控件。 | 525| CAMERA_SWITCH | 7 | 打开/关闭摄像头控件。 | 526| MUTE_SWITCH | 8 | 打开/关闭静音控件。 | 527 528 529## ControlPanelActionEventCallback<sup>12+</sup> 530 531type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 532 533描述画中画控制面板控件动作事件回调。 534 535**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 536 537**系统能力：** SystemCapability.Window.SessionManager 538 539**参数：** 540 541| 参数名 | 类型 | 必填 | 说明 | 542|--------------------------|--------------|--------------|-----------------------------------| 543| event | [PiPActionEventType](#pipactioneventtype) | 是 | 回调画中画控制面板控件动作事件类型。<br/>应用依据控件动作事件做相应处理，如触发'playbackStateChanged'事件时，需要开始或停止视频。 | 544| status | number | 否 | 表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为1，关闭为0。其余控件该参数返回默认值-1。 | 545 546## ControlEventParam<sup>12+</sup> 547 548画中画控制面板控件动作回调的参数。 549 550**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 551 552**系统能力：** SystemCapability.Window.SessionManager 553 554| 名称 | 类型 | 必填 | 说明 | 555|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 556| controlType | [PiPControlType](#pipcontroltype12) | 是 | 回调画中画控制面板控件动作事件类型。应用依据控件类型做相应处理，如视频模板中暂停/播放控件被点击时，需要开始或停止视频。 | 557| status | [PiPControlStatus](#pipcontrolstatus12) | 否 | 表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为PiPControlStatus.PLAY，关闭为PiPControlStatus.PAUSE。如不具备开/关和播放/暂停状态的挂断控件默认返回值为-1。 | 558 559## PiPController 560 561画中画控制器实例。用于启动、停止画中画以及更新回调注册等。 562 563下列API示例中都需先使用[PiPWindow.create()](#pipwindowcreate)方法获取到PiPController实例，再通过此实例调用对应方法。 564 565**系统能力：** SystemCapability.Window.SessionManager 566 567### startPiP 568 569startPiP(): Promise<void> 570 571启动画中画，使用Promise异步回调。 572 573**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 574 575**系统能力：** SystemCapability.Window.SessionManager 576 577**返回值：** 578 579| 类型 | 说明 | 580|------------------------|--------------------| 581| Promise<void> | 无返回结果的Promise对象。 | 582 583**错误码：** 584 585以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 586 587| 错误码ID | 错误信息 | 588|------------|--------------------------------------------------------| 589| 1300012 | The PiP window state is abnormal. | 590| 1300013 | Failed to create the PiP window. | 591| 1300014 | PiP internal error. | 592| 1300015 | Repeated PiP operation. | 593 594**示例：** 595 596```ts 597//开发者可根据pipController的定义方式自行实现pipController的调用 598let promise : Promise<void> = this.pipController.startPiP(); 599promise.then(() => { 600 console.info(`Succeeded in starting pip.`); 601}).catch((err: BusinessError) => { 602 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 603}); 604``` 605 606### stopPiP 607 608stopPiP(): Promise<void> 609 610停止画中画，使用Promise异步回调。 611 612**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 613 614**系统能力：** SystemCapability.Window.SessionManager 615 616**返回值：** 617 618| 类型 | 说明 | 619|----------------------|---------------------| 620| Promise<void> | 无返回结果的Promise对象。 | 621 622**错误码：** 623 624以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 625 626| 错误码ID | 错误信息 | 627|---------|-----------------------------------| 628| 1300011 | Failed to destroy the PiP window. | 629| 1300012 | The PiP window state is abnormal. | 630| 1300015 | Repeated PiP operation. | 631 632**示例：** 633 634```ts 635let promise : Promise<void> = this.pipController.stopPiP(); 636promise.then(() => { 637 console.info(`Succeeded in stopping pip.`); 638}).catch((err: BusinessError) => { 639 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 640}); 641``` 642 643### setAutoStartEnabled 644 645setAutoStartEnabled(enable: boolean): void 646 647设置是否在返回桌面时自动启动画中画，默认不自动拉起。 648 649在使用xComponent方案实现画中画功能并结合Navigation进行路由管理时，首次调用setAutoStartEnabled(true)方法，系统会缓存当前应用传入的NavigationId的栈顶信息。 650 651**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 652 653**系统能力：** SystemCapability.Window.SessionManager 654 655**参数：** 656 657| 参数名 | 类型 | 必填 | 说明 | 658|----------|-----------|-------|---------------------------------| 659| enable | boolean | 是 | 如返回桌面时需自动启动画中画，则该参数配置为true，否则为false。若设置中自动启动画中画开关为关闭状态，就算该参数配置为true，应用返回桌面时也不会自动启动画中画窗口。 | 660 661**示例：** 662 663```ts 664let enable: boolean = true; 665this.pipController.setAutoStartEnabled(enable); 666``` 667 668### updateContentSize 669 670updateContentSize(width: number, height: number): void 671 672当媒体源切换时，向画中画控制器更新媒体源尺寸信息。 673 674**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 675 676**系统能力：** SystemCapability.Window.SessionManager 677 678**参数：** 679 680| 参数名 | 类型 | 必填 | 说明 | 681|--------|--------|-----|----------------------------------------| 682| width | number | 是 | 表示媒体内容宽度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。 | 683| height | number | 是 | 表示媒体内容高度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。 | 684 685**错误码：** 686 687以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 688 689| 错误码ID | 错误信息 | 690|-------|-------------------------------------------------------------------------------------------------------------| 691| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 692 693**示例：** 694 695```ts 696let width: number = 540; // 假设当前内容宽度变为540px。 697let height: number = 960; // 假设当前内容高度变为960px。 698this.pipController.updateContentSize(width, height); 699``` 700 701### updatePiPControlStatus<sup>12+</sup> 702updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 703 704更新画中画控制面板控件功能状态。 705 706**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 707 708**系统能力：** SystemCapability.Window.SessionManager 709 710**参数：** 711 712| 参数名 | 类型 | 必填 | 说明 | 713|--------|--------|-----|----------------------------------------------------------------------------------------------------| 714| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。目前仅支持VIDEO_PLAY_PAUSE、MICROPHONE_SWITCH、CAMERA_SWITCH和MUTE_SWITCH这几种控件类型，传入其他控件类型无效。 | 715| status | [PiPControlStatus](#pipcontrolstatus12) | 是 | 表示画中画控制面板控件状态。 | 716 717**错误码：** 718 719以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 720 721| 错误码ID | 错误信息 | 722|-------|-------------------------------------------------------------------------------------------------------------| 723| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 724 725**示例：** 726 727```ts 728let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 729let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // 视频播放控制面板中播放/暂停控件为播放状态。 730this.pipController.updatePiPControlStatus(controlType, status); 731``` 732 733### updateContentNode<sup>18+</sup> 734updateContentNode(contentNode: typeNode.XComponent): Promise<void> 735 736更新画中画节点内容。 737 738**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 739 740**系统能力：** SystemCapability.Window.SessionManager 741 742**参数：** 743 744| 参数名 | 类型 | 必填 | 说明 | 745|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 746| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | 是 | 用于渲染画中画窗口中的内容。该参数不能为空。| 747 748**返回值：** 749 750| 类型 | 说明 | 751|----------------------|---------------------| 752| Promise<void> | 无返回结果的Promise对象。 | 753 754**错误码：** 755 756以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 757 758| 错误码ID | 错误信息 | 759|-------|-------------------------------------------------------------------------------------------------------------| 760| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 761| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 762| 1300014 | PiP internal error. | 763 764**示例：** 765 766```ts 767import { typeNode, UIContext } from '@kit.ArkUI'; 768 769let context: UIContext | undefined = undefined; // 可传入UIContext或在布局中通过this.getUIContext()为context赋有效值 770 771try { 772 let contentNode = typeNode.createNode(context, "XComponent"); 773 this.pipController.updateContentNode(contentNode); 774} catch (exception) { 775 console.error(`Failed to update content node. Cause: ${exception.code}, message: ${exception.message}`); 776} 777``` 778 779### setPiPControlEnabled<sup>12+</sup> 780setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 781 782更新控制面板控件使能状态。 783 784**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 785 786**系统能力：** SystemCapability.Window.SessionManager 787 788**参数：** 789 790| 参数名 | 类型 | 必填 | 说明 | 791|-------------|--------|-----|----------------------------------------| 792| controlType | [PiPControlType](#pipcontroltype12) | 是 | 表示画中画控制面板控件类型。 | 793| enabled | boolean | 是 | 表示画中画控制面板控件使能状态。true表示控件为可使用状态，false则为禁用状态。 | 794 795**错误码：** 796 797以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 798 799| 错误码ID | 错误信息 | 800|-------|-------------------------------------------------------------------------------------------------------------| 801| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 802 803**示例：** 804 805```ts 806let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。 807let enabled: boolean = false; // 视频播放控制面板中播放/暂停控件为禁用状态。 808this.pipController.setPiPControlEnabled(controlType, enabled); 809``` 810### getPiPWindowInfo<sup>15+</sup> 811getPiPWindowInfo(): Promise<[PiPWindowInfo](#pipwindowinfo15)> 812 813获取画中画窗口信息。 814 815**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 816 817**系统能力：** SystemCapability.Window.SessionManager 818 819**返回值：** 820 821| 类型 | 说明 | 822|----------------------|---------------------| 823| Promise<[PiPWindowInfo](#pipwindowinfo15)> | Promise对象，返回当前画中画窗口信息。 | 824 825**错误码：** 826 827以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 828 829| 错误码ID | 错误信息 | 830|-------|-------------------------------------------------------------------------------------------------------------| 831| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 832| 1300014 | PiP internal error. | 833 834**示例：** 835 836```ts 837let pipWindowInfo: PiPWindow.PiPWindowInfo | undefined = undefined; 838try { 839 let promise : Promise<PiPWindow.PiPWindowInfo> = this.pipController.getPiPWindowInfo(); 840 promise.then((data) => { 841 pipWindowInfo = data; 842 console.info('Success in get pip window info. Info: ' + JSON.stringify(data)); 843 }).catch((err: BusinessError) => { 844 console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`); 845 }); 846} catch (exception) { 847 console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`); 848} 849``` 850 851### getPiPSettingSwitch<sup>20+</sup> 852getPiPSettingSwitch(): Promise<boolean> 853 854获取设置中自动启动画中画开关的状态。 855 856**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 857 858**系统能力：** SystemCapability.Window.SessionManager 859 860**设备行为差异：** 该接口在Phone设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 861 862**返回值：** 863 864| 类型 | 说明 | 865|----------------------|---------------------| 866| Promise<boolean> | Promise对象，返回当前自动启动画中画开关状态，true表示开启，false表示关闭。 | 867 868**错误码：** 869 870以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 871 872| 错误码ID | 错误信息 | 873|-------|-------------------------------------------------------------------------------------------------------------| 874| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 875| 1300014 | PiP internal error. | 876 877**示例：** 878 879```ts 880let pipSwitchStatus: boolean | undefined = undefined; 881try { 882 let promise : Promise<boolean> = this.pipController.getPiPSettingSwitch(); 883 promise.then((data) => { 884 pipSwitchStatus = data; 885 console.info('Succeeded in getting pip switch status. switchStatus: ' + JSON.stringify(data)); 886 }).catch((err: BusinessError) => { 887 console.error(`Failed to get pip switch status. Cause code: ${err.code}, message: ${err.message}`); 888 }); 889} catch (exception) { 890 console.error(`Failed to get pip switch status. Cause code: ${exception.code}, message: ${exception.message}`); 891} 892``` 893 894### on('stateChange') 895 896on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 897 898开启画中画生命周期状态的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。 899 900**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 901 902**系统能力：** SystemCapability.Window.SessionManager 903 904**参数：** 905 906| 参数名 | 类型 | 必填 | 说明 | 907|------------|-----------|------|---------------------------------------------------------------------------------------------------| 908| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 909| callback | function | 是 | 回调生命周期状态变化事件以及原因。<br/>state：[PiPState](#pipstate)，表示当前画中画生命周期状态。<br/>reason：string，表示当前生命周期的切换原因。 | 910 911**示例：** 912 913```ts 914this.pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 915 let curState: string = ''; 916 switch (state) { 917 case PiPWindow.PiPState.ABOUT_TO_START: 918 curState = 'ABOUT_TO_START'; 919 break; 920 case PiPWindow.PiPState.STARTED: 921 curState = 'STARTED'; 922 break; 923 case PiPWindow.PiPState.ABOUT_TO_STOP: 924 curState = 'ABOUT_TO_STOP'; 925 break; 926 case PiPWindow.PiPState.STOPPED: 927 curState = 'STOPPED'; 928 break; 929 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 930 curState = 'ABOUT_TO_RESTORE'; 931 break; 932 case PiPWindow.PiPState.ERROR: 933 curState = 'ERROR'; 934 break; 935 default: 936 break; 937 } 938 console.info('stateChange:' + curState + ' reason:' + reason); 939}); 940``` 941 942### off('stateChange') 943 944off(type: 'stateChange'): void 945 946关闭画中画生命周期状态的监听。 947 948**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 949 950**系统能力：** SystemCapability.Window.SessionManager 951 952**参数：** 953 954| 参数名 | 类型 | 必填 | 说明 | 955|-----------|---------------|-------|----------------------------------------| 956| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 957 958**示例：** 959 960```ts 961this.pipController.off('stateChange'); 962``` 963 964### on('controlPanelActionEvent') 965 966on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 967 968开启画中画控制面板控件动作事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。推荐使用[on('controlEvent')](#oncontrolevent12)来开启画中画控制面板控件动作事件的监听。 969 970**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 971 972**系统能力：** SystemCapability.Window.SessionManager 973 974**参数：** 975 976| 参数名 | 类型 | 必填 | 说明 | 977|----------|------------|-------|---------------------------------------------------| 978| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。 | 979| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | 是 | 描述画中画控制面板控件动作事件回调。 | 980 981**示例：** 982 983```ts 984this.pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 985 switch (event) { 986 case 'playbackStateChanged': 987 if (status === 0) { 988 //停止视频 989 } else if (status === 1) { 990 //播放视频 991 } 992 break; 993 case 'nextVideo': 994 // 切换到下一个视频 995 break; 996 case 'previousVideo': 997 // 切换到上一个视频 998 break; 999 case 'fastForward': 1000 // 视频进度快进 1001 break; 1002 case 'fastBackward': 1003 // 视频进度后退 1004 break; 1005 default: 1006 break; 1007 } 1008 console.info('registerActionEventCallback, event:' + event); 1009}); 1010``` 1011 1012### on('controlEvent')<sup>12+</sup> 1013 1014on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 1015 1016开启画中画控制面板控件动作事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。 1017 1018**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1019 1020**系统能力：** SystemCapability.Window.SessionManager 1021 1022**参数：** 1023 1024| 参数名 | 类型 | 必填 | 说明 | 1025|----------|-----------------------------------------------------|-------|----------------------------------------| 1026| type | string | 是 | 监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。 | 1027| callback | Callback<[ControlEventParam](#controleventparam12)> | 是 | 描述画中画控制面板控件动作事件回调。 | 1028 1029**示例：** 1030 1031```ts 1032this.pipController.on('controlEvent', (control) => { 1033 switch (control.controlType) { 1034 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 1035 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 1036 //停止视频 1037 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 1038 //播放视频 1039 } 1040 break; 1041 case PiPWindow.PiPControlType.VIDEO_NEXT: 1042 // 切换到下一个视频 1043 break; 1044 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 1045 // 切换到上一个视频 1046 break; 1047 case PiPWindow.PiPControlType.FAST_FORWARD: 1048 // 视频进度快进 1049 break; 1050 case PiPWindow.PiPControlType.FAST_BACKWARD: 1051 // 视频进度后退 1052 break; 1053 default: 1054 break; 1055 } 1056 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 1057}); 1058``` 1059 1060### off('controlPanelActionEvent') 1061 1062off(type: 'controlPanelActionEvent'): void 1063 1064关闭画中画控制面板控件动作事件的监听。推荐使用[off('controlEvent')](#offcontrolevent12)来关闭画中画控制面板控件动作事件的监听。 1065 1066**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1067 1068**系统能力：** SystemCapability.Window.SessionManager 1069 1070**参数：** 1071 1072| 参数名 | 类型 | 必填 | 说明 | 1073|------------|------------------------------|------|-----------------------------------------------| 1074| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。 | 1075 1076**示例：** 1077 1078```ts 1079this.pipController.off('controlPanelActionEvent'); 1080``` 1081 1082### off('controlEvent')<sup>12+</sup> 1083 1084off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 1085 1086关闭画中画控制面板控件动作事件的监听。 1087 1088**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1089 1090**系统能力：** SystemCapability.Window.SessionManager 1091 1092**参数：** 1093 1094| 参数名 | 类型 | 必填 | 说明 | 1095|------------|-----------------------------------------------------|----|--------------------------------------------------------| 1096| type | string | 是 | 监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。 | 1097| callback | Callback<[ControlEventParam](#controleventparam12)> | 否 | 描述画中画控制面板控件动作事件回调。如果不传该参数时，解除type为'controlEvent'的所有回调。 | 1098 1099**示例：** 1100 1101```ts 1102this.pipController.off('controlEvent', () => {}); 1103``` 1104 1105### on('pipWindowSizeChange')<sup>15+</sup> 1106 1107on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void 1108 1109开启画中画窗口尺寸变化事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。 1110 1111**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1112 1113**系统能力：** SystemCapability.Window.SessionManager 1114 1115**参数：** 1116 1117| 参数名 | 类型 | 必填 | 说明 | 1118|----------|---------------------------------------------|-------|---------------------------------------------------| 1119| type | string | 是 | 监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。 | 1120| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | 是 | 回调函数。返回当前画中画窗口的尺寸。 | 1121 1122**错误码：** 1123 1124以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1125 1126| 错误码ID | 错误信息 | 1127| ------- | -------------------------------------------- | 1128| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1129| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1130| 1300014 | PiP internal error. | 1131 1132**示例：** 1133 1134```ts 1135try { 1136 this.pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => { 1137 console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size)); 1138 }); 1139} catch (exception) { 1140 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1141} 1142``` 1143 1144### off('pipWindowSizeChange')<sup>15+</sup> 1145 1146off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void 1147 1148关闭画中画窗口尺寸变化事件的监听。 1149 1150**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1151 1152**系统能力：** SystemCapability.Window.SessionManager 1153 1154**参数：** 1155 1156| 参数名 | 类型 | 必填 | 说明 | 1157|----------|------------|----|---------------------------------------------------------------------| 1158| type | string | 是 | 监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。 | 1159| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | 否 | 回调函数。返回当前画中画窗口的尺寸。如果传入参数，则关闭该监听。如果未传入参数，解除type为'pipWindowSizeChange'的所有回调。 | 1160 1161**错误码：** 1162 1163以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1164 1165| 错误码ID | 错误信息 | 1166| ------- | -------------------------------------------- | 1167| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1168| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1169 1170**示例：** 1171 1172```ts 1173const callback = (size: PiPWindow.PiPWindowSize) => { 1174 // ... 1175} 1176try { 1177 // 通过on接口开启监听 1178 this.pipController.on('pipWindowSizeChange', callback); 1179} catch (exception) { 1180 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1181} 1182 1183try { 1184 // 关闭指定callback的监听 1185 this.pipController.off('pipWindowSizeChange', callback); 1186 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 1187 this.pipController.off('pipWindowSizeChange'); 1188} catch (exception) { 1189 console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1190} 1191```