1# @ohos.PiPWindow (画中画窗口) 2 3该模块提供画中画基础功能，包括判断当前系统是否开启画中画功能，以及创建画中画控制器用于启动、停止画中画等。主要用于视频播放、视频通话或视频会议场景下，以小窗（画中画）模式呈现内容。 4 5> **说明：** 6> 7> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块，参考[系统能力SystemCapability使用指南](../syscap.md)。 10 11## 导入模块 12 13```ts 14import pipWindow from '@ohos.PiPWindow'; 15``` 16 17## pipWindow.isPiPEnabled 18 19isPiPEnabled(): boolean 20 21用于判断当前系统是否开启画中画功能。 22 23**系统能力：** SystemCapability.Window.SessionManager 24 25**返回值：** 26 27| 类型 | 说明 | 28|----------|-------------------------------------| 29| boolean | 当前系统是否开启画中画功能。true表示开启，false则表示未开启。 | 30 31**示例：** 32 33```ts 34let enable: boolean = pipWindow.isPiPEnabled(); 35console.info('isPipEnabled:' + enable); 36``` 37 38## pipWindow.create 39 40create(config: PiPConfiguration): Promise<PiPController> 41 42创建画中画控制器，使用Promise异步回调。 43 44**系统能力：** SystemCapability.Window.SessionManager 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49|--------------|------------------------------------------|-----------|----------------| 50| config | [PiPConfiguration](#pipconfiguration) | 是 | 创建画中画控制器的参数。 | 51 52**返回值：** 53 54| 类型 | 说明 | 55|------------------------------------------------------------|--------------------------| 56| Promise<[PiPController](#pipcontroller)> | Promise对象。返回当前创建的画中画控制器。 | 57 58**示例：** 59 60```ts 61import { BusinessError } from '@ohos.base'; 62let pipController: pipWindow.PiPController | undefined = undefined; 63let mXComponentController: XComponentController = new XComponentController(); // 开发者应使用该mXComponentController初始化XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} )，保证XComponent的内容可以被迁移到画中画窗口。 64let navId: string = "page_1"; // 假设当前页面的导航id为page_1，详见PiPConfiguration定义，具体导航名称由开发者自行定义。 65let contentWidth: number = 800; // 假设当前内容宽度800px。 66let contentHeight: number = 600; // 假设当前内容高度600px。 67let config: pipWindow.PiPConfiguration = { 68 context: getContext(this), 69 componentController: mXComponentController, 70 navigationId: navId, 71 templateType: pipWindow.PiPTemplateType.VIDEO_PLAY, 72 contentWidth: contentWidth, 73 contentHeight: contentHeight, 74}; 75 76let promise : Promise<pipWindow.PiPController> = pipWindow.create(config); 77promise.then((data : pipWindow.PiPController) => { 78 pipController = data; 79 console.info(`Succeeded in creating pip controller. Data:${data}`); 80}).catch((err: BusinessError) => { 81 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 82}); 83``` 84 85## PiPConfiguration 86 87创建画中画控制器时的参数。 88 89**系统能力：** SystemCapability.Window.SessionManager 90 91| 名称 | 类型 | 必填 | 说明 | 92|---------------------|-----------------------------------------------------------------------|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 93| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 表示上下文环境。 | 94| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md) | 是 | 表示原始[XComponent](../../ui/arkts-common-components-xcomponent.md)控制器。 | 95| 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，还原场景下也能够从画中画窗口恢复到原页面。 | 96| templateType | [PiPTemplateType](#piptemplatetype) | 否 | 模板类型，用以区分视频播放、视频通话或视频会议。 | 97| contentWidth | number | 否 | 原始内容宽度，单位为px。用于确定画中画窗口比例。 | 98| contentHeight | number | 否 | 原始内容高度，单位为px。用于确定画中画窗口比例。 | 99 100## PiPTemplateType 101 102画中画媒体类型枚举。 103 104**系统能力：** SystemCapability.Window.SessionManager 105 106| 名称 | 值 | 说明 | 107|---------------|-----|--------------------------------------| 108| VIDEO_PLAY | 0 | 表示将要切换为画中画播放的媒体类型是视频，系统依此加载视频播放模板。 | 109| VIDEO_CALL | 1 | 表示将要切换为画中画播放的媒体类型是视频通话，系统依此加载视频通话模板。 | 110| VIDEO_MEETING | 2 | 表示将要切换为画中画播放的媒体类型是视频会议，系统依此加载视频会议模板。 | 111| VIDEO_LIVE | 3 | 表示将要切换为画中画播放的媒体类型是直播，系统依此加载直播模板。 | 112 113## PiPState 114 115画中画生命周期状态枚举。 116 117**系统能力：** SystemCapability.Window.SessionManager 118 119| 名称 | 值 | 说明 | 120|----------------------|-----|-----------------------| 121| ABOUT_TO_START | 1 | 表示画中画将要启动。 | 122| STARTED | 2 | 表示画中画已经启动。 | 123| ABOUT_TO_STOP | 3 | 表示画中画将要停止。 | 124| STOPPED | 4 | 表示画中画已经停止。 | 125| ABOUT_TO_RESTORE | 5 | 表示画中画将从小窗播放恢复到原始播放界面。 | 126| ERROR | 6 | 表示画中画生命周期执行过程出现了异常。 | 127 128## PiPActionEventType 129 130画中画控制事件类型，支持以下四种。 131 132**系统能力：** SystemCapability.Window.SessionManager 133 134| 类型 | 说明 | 135|-------------------------------------------------|-------------| 136| [PiPVideoActionEvent](#pipvideoactionevent) | 视频播放控制事件类型。 | 137| [PiPCallActionEvent](#pipcallactionevent) | 视频通话控制事件类型。 | 138| [PiPMeetingActionEvent](#pipmeetingactionevent) | 视频会议控制事件类型。 | 139| [PiPLiveActionEvent](#pipliveactionevent) | 直播控制事件类型。 | 140 141## PiPVideoActionEvent 142 143视频播放控制事件类型。 144 145**系统能力：** SystemCapability.Window.SessionManager 146 147| 名称 | 类型 | 说明 | 148|------------------------|----------|-----------------------------------------------------------------------------------------------------| 149| PiPVideoActionEvent | string | 有以下取值：<br/>-'playbackStateChanged'：播放状态发生了变化。<br>-'nextVideo'：播放下一个视频。<br>-'previousVideo'：播放上一个视频。 | 150 151## PiPCallActionEvent 152 153视频通话控制事件类型。 154 155**系统能力：** SystemCapability.Window.SessionManager 156 157| 名称 | 类型 | 说明 | 158|------------------------|--------|------------------------------------------------------------------------------------------------| 159| PiPCallActionEvent | string | 有以下取值：<br/>-'hangUp'：挂断视频通话。<br>-'micStateChanged'：打开或关闭麦克风。<br>-'videoStateChanged'：打开或关闭摄像头。 | 160 161## PiPMeetingActionEvent 162 163视频会议控制事件类型。 164 165**系统能力：** SystemCapability.Window.SessionManager 166 167| 名称 | 类型 | 说明 | 168|----------------------------|------------|-------------------------------------------------------------------------------------------------| 169| PiPMeetingActionEvent | string | 有以下取值：<br/>-'hangUp'：挂断视频会议。<br>-'voiceStateChanged'：静音或解除静音。<br>-'videoStateChanged'：打开或关闭摄像头。 | 170 171## PiPLiveActionEvent 172 173直播控制事件类型。 174 175**系统能力：** SystemCapability.Window.SessionManager 176 177| 名称 | 类型 | 说明 | 178|--------------------------|--------------|-----------------------------------| 179| PiPLiveActionEvent | string | 值为'playbackStateChanged'：播放或暂停直播。 | 180 181## PiPController 182 183画中画控制器实例。用于启动、停止画中画以及更新回调注册等。 184 185下列API示例中都需先使用[pipWindow.create()](#pipwindowcreate)方法获取到PiPController实例，再通过此实例调用对应方法。 186 187**系统能力：** SystemCapability.Window.SessionManager 188 189### startPiP 190 191startPiP(): Promise<void> 192 193启动画中画，使用Promise异步回调。 194 195**系统能力：** SystemCapability.Window.SessionManager 196 197**返回值：** 198 199| 类型 | 说明 | 200|------------------------|--------------------| 201| Promise<void> | 无返回结果的Promise对象。 | 202 203**错误码：** 204 205以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 206 207| 错误码ID | 错误信息 | 208|------------|--------------------------------------------------------| 209| 1300012 | If PiP window state is abnormal. | 210| 1300013 | Create pip window failed. | 211| 1300014 | Error when load PiP window content or show PiP window. | 212| 1300015 | If window has created. | 213 214**示例：** 215 216```ts 217let promise : Promise<void> = pipController.startPiP(); 218promise.then(() => { 219 console.info(`Succeeded in starting pip.`); 220}).catch((err: BusinessError) => { 221 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 222}); 223``` 224 225### stopPiP 226 227stopPiP(): Promise<void> 228 229停止画中画，使用Promise异步回调。 230 231**系统能力：** SystemCapability.Window.SessionManager 232 233**返回值：** 234 235| 类型 | 说明 | 236|----------------------|---------------------| 237| Promise<void> | 无返回结果的Promise对象。 | 238 239**错误码：** 240 241以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 242 243| 错误码ID | 错误信息 | 244|---------|----------------------------------| 245| 1300011 | Stop PiP window failed. | 246| 1300012 | If PiP window state is abnormal. | 247| 1300015 | If window is stopping. | 248 249**示例：** 250 251```ts 252let promise : Promise<void> = pipController.stopPiP(); 253promise.then(() => { 254 console.info(`Succeeded in stopping pip.`); 255}).catch((err: BusinessError) => { 256 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 257}); 258``` 259 260### setAutoStartEnabled 261 262setAutoStartEnabled(enable: boolean): void 263 264设置是否需要在返回桌面时自动启动画中画。 265 266**系统能力：** SystemCapability.Window.SessionManager 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271|----------|-----------|-------|---------------------------------| 272| enable | boolean | 是 | true表示设置返回桌面时自动启动画中画，否则为false。 | 273 274```ts 275let enable: boolean = true; 276pipController.setAutoStartEnabled(enable); 277``` 278 279### updateContentSize 280 281updateContentSize(width: number, height: number): void 282 283当媒体源切换时，向画中画控制器更新媒体源尺寸信息。 284 285**系统能力：** SystemCapability.Window.SessionManager 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290|--------|--------|-----|------------------------------| 291| width | number | 是 | 表示媒体内容宽度，单位为px。用于更新画中画窗口比例。 | 292| height | number | 是 | 表示媒体内容高度，单位为px。用于更新画中画窗口比例。 | 293 294```ts 295let width: number = 540; // 假设当前内容宽度变为540px。 296let height: number = 960; // 假设当前内容高度变为960px。 297pipController.updateContentSize(width, height); 298``` 299 300### on('stateChange') 301 302on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 303 304开启画中画生命周期状态的监听。 305 306**系统能力：** SystemCapability.Window.SessionManager 307 308**参数：** 309 310| 参数名 | 类型 | 必填 | 说明 | 311|------------|-----------|------|---------------------------------------------------------------------------------------------------| 312| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 313| callback | function | 是 | 回调生命周期状态变化事件以及原因：<br/>state：[PiPState](#pipstate)，表示当前画中画生命周期状态；<br/>reason：string，表示当前生命周期的切换原因。 | 314 315```ts 316pipController.on('stateChange', (state: pipWindow.PiPState, reason: string) => { 317 let curState: string = ''; 318 switch (state) { 319 case pipWindow.PiPState.ABOUT_TO_START: 320 curState = 'ABOUT_TO_START'; 321 break; 322 case pipWindow.PiPState.STARTED: 323 curState = 'STARTED'; 324 break; 325 case pipWindow.PiPState.ABOUT_TO_STOP: 326 curState = 'ABOUT_TO_STOP'; 327 break; 328 case pipWindow.PiPState.STOPPED: 329 curState = 'STOPPED'; 330 break; 331 case pipWindow.PiPState.ABOUT_TO_RESTORE: 332 curState = 'ABOUT_TO_RESTORE'; 333 break; 334 case pipWindow.PiPState.ERROR: 335 curState = 'ERROR'; 336 break; 337 default: 338 break; 339 } 340 console.info('stateChange:' + curState + ' reason:' + reason); 341}); 342``` 343 344### off('stateChange') 345 346off(type: 'stateChange'): void 347 348关闭画中画生命周期状态的监听。 349 350**系统能力：** SystemCapability.Window.SessionManager 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355|-----------|---------------|-------|----------------------------------------| 356| type | string | 是 | 监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。 | 357 358**示例：** 359 360```ts 361pipController.off('stateChange'); 362``` 363 364### on('controlPanelActionEvent') 365 366on(type: 'controlPanelActionEvent', callback: (event: PiPActionEventType) => void): void 367 368开启画中画控制事件的监听。 369 370**系统能力：** SystemCapability.Window.SessionManager 371 372**参数：** 373 374| 参数名 | 类型 | 必填 | 说明 | 375|----------|------------|-------|--------------------------------------------------------------------------------------------------------------------------------| 376| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制事件。 | 377| callback | function | 是 | 回调画中画控制事件:<br/>event: [PiPActionEventType](#pipactioneventtype)，表示控制事件类型。应用依据控制事件做相应处理，如触发'playbackStateChanged'事件时，需要开始或停止视频。 | 378 379```ts 380pipController.on('controlPanelActionEvent', (event: pipWindow.PiPActionEventType) => { 381 switch (event) { 382 case 'playbackStateChanged': 383 // 开始或停止视频 384 break; 385 case 'nextVideo': 386 // 切换到下一个视频 387 break; 388 case 'previousVideo': 389 // 切换到上一个视频 390 break; 391 default: 392 break; 393 } 394 console.info('registerActionEventCallback, event:' + event); 395}); 396``` 397 398### off('controlPanelActionEvent') 399 400off(type: 'controlPanelActionEvent'): void 401 402关闭画中画控制事件的监听。 403 404**系统能力：** SystemCapability.Window.SessionManager 405 406**参数：** 407 408| 参数名 | 类型 | 必填 | 说明 | 409|------------|------------------------------|------|-----------------------------------------------| 410| type | string | 是 | 监听事件，固定为'controlPanelActionEvent'，即画中画控制事件。 | 411 412**示例：** 413 414```ts 415pipController.off('controlPanelActionEvent'); 416```