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