1# @ohos.PiPWindow (PiP Window) 2 3The **PiPWindow** module provides basic APIs for manipulating Picture in Picture (PiP). For example, you can use the APIs to check whether the PiP feature is enabled and create a PiP controller to start or stop a PiP window. PiP is mainly used in video playback, video call, or video meeting scenarios. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> This module must be used on the device that supports the **SystemCapability.Window.SessionManager** capability. For details, see [SystemCapability](../syscap.md). 10 11## Modules to Import 12 13```ts 14import pipWindow from '@ohos.PiPWindow'; 15``` 16 17## pipWindow.isPiPEnabled 18 19isPiPEnabled(): boolean 20 21Checks whether the PiP feature is enabled. 22 23**System capability**: SystemCapability.Window.SessionManager 24 25**Return value** 26 27| Type | Description | 28|----------|-------------------------------------| 29| boolean | Status of the PiP feature. The value **true** means that the PiP feature is enabled, and **false** means the opposite.| 30 31**Example** 32 33```ts 34let enable: boolean = pipWindow.isPiPEnabled(); 35console.info('isPipEnabled:' + enable); 36``` 37 38## pipWindow.create 39 40create(config: PiPConfiguration): Promise<PiPController> 41 42Creates a PiP controller. This API uses a promise to return the result. 43 44**System capability**: SystemCapability.Window.SessionManager 45 46**Parameters** 47 48| Name | Type | Mandatory | Description | 49|--------------|------------------------------------------|-----------|----------------| 50| config | [PiPConfiguration](#pipconfiguration) | Yes | Parameters for creating the PiP controller. | 51 52**Return value** 53 54| Type | Description | 55|------------------------------------------------------------|--------------------------| 56| Promise<[PiPController](#pipcontroller)> | Promise used to return the PiP controller.| 57 58**Example** 59 60```ts 61import { BusinessError } from '@ohos.base'; 62let pipController: pipWindow.PiPController | undefined = undefined; 63let mXComponentController: XComponentController = new XComponentController(); // Use the mXComponentController to initialize the XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} ). This ensures that the XComponent content can be migrated to the PiP window. 64let navId: string = "page_1"; // The navigation ID of the current page is page_1. For details, see the definition of PiPConfiguration. The navigation name is customized. 65let contentWidth: number = 800; // The content width is 800 px. 66let contentHeight: number = 600; // The content height is 600 px. 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 87Defines the parameters for creating a PiP controller. 88 89**System capability**: SystemCapability.Window.SessionManager 90 91| Name | Type | Mandatory | Description | 92|---------------------|-----------------------------------------------------------------------|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 93| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Context environment. | 94| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md) | Yes | Original [XComponent](../../ui/arkts-common-components-xcomponent.md) controller. | 95| navigationId | string | No | Navigation ID of the current page.<br>1. When the UIAbility uses [Navigation](arkui-ts/ts-basic-components-navigation.md) to manage pages, set the ID of the **<\Navigation>** component for the PiP controller. This ensures that the original page can be restored from the PiP window.<br>2. When the UIAbility uses [Router](js-apis-router.md) to manage pages, you do not need to set the navigation ID. (This navigation mode is not recommended in PiP scenarios.) After a PiP window is started in this scenario, do not switch between pages. Otherwise, exceptions may occur during restoration.<br>3. If the UIAbility has only one page, you do not need to set the navigation ID. The original page can be restored from the PiP window.| 96| templateType | [PiPTemplateType](#piptemplatetype) | No | Template type, which is used to distinguish video playback, video call, and video meeting scenarios. | 97| contentWidth | number | No | Width of the original content, in px. It is used to determine the aspect ratio of the PiP window. | 98| contentHeight | number | No | Height of the original content, in px. It is used to determine the aspect ratio of the PiP window. | 99 100## PiPTemplateType 101 102Enumerates the PIP template types. 103 104**System capability**: SystemCapability.Window.SessionManager 105 106| Name | Value | Description | 107|---------------|-----|--------------------------------------| 108| VIDEO_PLAY | 0 | Video playback template. A PiP window will be started during video playback, and the video playback template is loaded. | 109| VIDEO_CALL | 1 | Video call template. A PiP window will be started during a video call, and the video call template will be loaded.| 110| VIDEO_MEETING | 2 | Video meeting template. A PiP window will be started during a video meeting, and the video meeting template will be loaded.| 111| VIDEO_LIVE | 3 | Live template. A PiP window will be started during a live, and the live template is loaded. | 112 113## PiPState 114 115Enumerates the PiP states. 116 117**System capability**: SystemCapability.Window.SessionManager 118 119| Name | Value | Description | 120|----------------------|-----|-----------------------| 121| ABOUT_TO_START | 1 | PiP is about to start. | 122| STARTED | 2 | PiP is started. | 123| ABOUT_TO_STOP | 3 | PiP is about to stop. | 124| STOPPED | 4 | PiP is stopped. | 125| ABOUT_TO_RESTORE | 5 | The original page is about to restore.| 126| ERROR | 6 | An error occurs during the execution of the PiP lifecycle. | 127 128## PiPActionEventType 129 130Enumerates the PiP action event types. 131 132**System capability**: SystemCapability.Window.SessionManager 133 134| Type | Description | 135|-------------------------------------------------|-------------| 136| [PiPVideoActionEvent](#pipvideoactionevent) | PiP action event during video playback.| 137| [PiPCallActionEvent](#pipcallactionevent) | PiP action event in a video call.| 138| [PiPMeetingActionEvent](#pipmeetingactionevent) | PiP action event in a video meeting.| 139| [PiPLiveActionEvent](#pipliveactionevent) | PiP action event in a live. | 140 141## PiPVideoActionEvent 142 143Defines the PiP action event during video playback. 144 145**System capability**: SystemCapability.Window.SessionManager 146 147| Name | Type | Description | 148|------------------------|----------|-----------------------------------------------------------------------------------------------------| 149| PiPVideoActionEvent | string | The options are as follows:<br>- **'playbackStateChanged'**: The playback status changes.<br>- **'nextVideo'**: Play the next video.<br>- **'previousVideo'**: Play the previous video.| 150 151## PiPCallActionEvent 152 153Defines the PiP action event in a video call. 154 155**System capability**: SystemCapability.Window.SessionManager 156 157| Name | Type | Description | 158|------------------------|--------|------------------------------------------------------------------------------------------------| 159| PiPCallActionEvent | string | The options are as follows:<br>- **'hangUp'**: The video call is hung up.<br>- **'micStateChanged'**: The microphone is muted or unmuted.<br>- **'videoStateChanged'**: The camera is turned on or off.| 160 161## PiPMeetingActionEvent 162 163Defines the PiP action event in a video meeting. 164 165**System capability**: SystemCapability.Window.SessionManager 166 167| Name | Type | Description | 168|----------------------------|------------|-------------------------------------------------------------------------------------------------| 169| PiPMeetingActionEvent | string | The options are as follows:<br>- **'hangUp'**: The video meeting is hung up.<br>- **'voiceStateChanged'**: The speaker is muted or unmuted.<br>- **'videoStateChanged'**: The camera is turned on or off.| 170 171## PiPLiveActionEvent 172 173Defines the PiP action event in a live. 174 175**System capability**: SystemCapability.Window.SessionManager 176 177| Name | Type | Description | 178|--------------------------|--------------|-----------------------------------| 179| PiPLiveActionEvent | string | **'playbackStateChanged'**: The live is played or paused.| 180 181## PiPController 182 183Implements a PiP controller that starts, stops, or updates a PiP window and registers callbacks. 184 185Before calling any of the following APIs, you must use [pipWindow.create()](#pipwindowcreate) to create a **PiPController** instance. 186 187**System capability**: SystemCapability.Window.SessionManager 188 189### startPiP 190 191startPiP(): Promise<void> 192 193Starts a PiP window. This API uses a promise to return the result. 194 195**System capability**: SystemCapability.Window.SessionManager 196 197**Return value** 198 199| Type | Description | 200|------------------------|--------------------| 201| Promise<void> | Promise that returns no value. | 202 203**Error codes** 204 205For details about the error codes, see [Window Error Codes](errorcode-window.md). 206 207| ID | Error Message | 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**Example** 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 229Stops a PiP window. This API uses a promise to return the result. 230 231**System capability**: SystemCapability.Window.SessionManager 232 233**Return value** 234 235| Type | Description | 236|----------------------|---------------------| 237| Promise<void> | Promise that returns no value. | 238 239**Error codes** 240 241For details about the error codes, see [Window Error Codes](errorcode-window.md). 242 243| ID | Error Message | 244|---------|----------------------------------| 245| 1300011 | Stop PiP window failed. | 246| 1300012 | If PiP window state is abnormal. | 247| 1300015 | If window is stopping. | 248 249**Example** 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 264Sets whether to automatically start a PiP window when the user returns to the home screen. 265 266**System capability**: SystemCapability.Window.SessionManager 267 268**Parameters** 269 270| Name | Type | Mandatory | Description | 271|----------|-----------|-------|---------------------------------| 272| enable | boolean | Yes | The value **true** means to automatically start a PiP window in such a case, and **false** means the opposite. | 273 274```ts 275let enable: boolean = true; 276pipController.setAutoStartEnabled(enable); 277``` 278 279### updateContentSize 280 281updateContentSize(width: number, height: number): void 282 283Updates the media content size when the media content is switched. 284 285**System capability**: SystemCapability.Window.SessionManager 286 287**Parameters** 288 289| Name | Type | Mandatory | Description | 290|--------|--------|-----|------------------------------| 291| width | number | Yes | Width of the media content, in px. It is used to update the aspect ratio of the PiP window. | 292| height | number | Yes | Width of the media content, in px. It is used to update the aspect ratio of the PiP window. | 293 294```ts 295let width: number = 540; // The content width changes to 540 px. 296let height: number = 960; // The content height changes to 960 px. 297pipController.updateContentSize(width, height); 298``` 299 300### on('stateChange') 301 302on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 303 304Subscribes to PiP state events. 305 306**System capability**: SystemCapability.Window.SessionManager 307 308**Parameters** 309 310| Name | Type | Mandatory | Description | 311|------------|-----------|------|---------------------------------------------------------------------------------------------------| 312| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 313| callback | function | Yes | Callback used to return the result, which includes the following information:<br>- **state**: [PiPState](#pipstate), indicating the new PiP state.<br>- **reason**: a string indicating the reason for the state change. | 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 348Unsubscribes from PiP state events. 349 350**System capability**: SystemCapability.Window.SessionManager 351 352**Parameters** 353 354| Name | Type | Mandatory | Description | 355|-----------|---------------|-------|----------------------------------------| 356| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 357 358**Example** 359 360```ts 361pipController.off('stateChange'); 362``` 363 364### on('controlPanelActionEvent') 365 366on(type: 'controlPanelActionEvent', callback: (event: PiPActionEventType) => void): void 367 368Subscribes to PiP action events. 369 370**System capability**: SystemCapability.Window.SessionManager 371 372**Parameters** 373 374| Name | Type | Mandatory | Description | 375|----------|------------|-------|--------------------------------------------------------------------------------------------------------------------------------| 376| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 377| callback | function | Yes | Callback used to return the result, which includes the following information:<br>**event**: [PiPActionEventType](#pipactioneventtype), indicating the type of the PiP action event. The application performs processing based on the event. For example, if the **'playbackStateChanged'** event is triggered, the application starts or stops the video.| 378 379```ts 380pipController.on('controlPanelActionEvent', (event: pipWindow.PiPActionEventType) => { 381 switch (event) { 382 case 'playbackStateChanged': 383 // Start or stop the video. 384 break; 385 case 'nextVideo': 386 // Switch to the next video. 387 break; 388 case 'previousVideo': 389 // Switch to the previous video. 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 402Unsubscribes from PiP action events. 403 404**System capability**: SystemCapability.Window.SessionManager 405 406**Parameters** 407 408| Name | Type | Mandatory | Description | 409|------------|------------------------------|------|-----------------------------------------------| 410| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 411 412**Example** 413 414```ts 415pipController.off('controlPanelActionEvent'); 416``` 417