1# @ohos.arkui.uiExtension (uiExtension) 2 3The **uiExtension** module provides APIs for the EmbeddedUIExtensionAbility (or UIExtensionAbility) to obtain the host application window information or the information about the corresponding **EmbeddedComponent**<!--Del--> (or **UIExtensionComponent**)<!--DelEnd--> component. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 8> 9 10## Modules to Import 11 12``` 13import { uiExtension } from '@kit.ArkUI' 14``` 15 16## WindowProxy 17 18### getWindowAvoidArea 19 20getWindowAvoidArea(type: window.AvoidAreaType): window.AvoidArea 21 22Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. 23 24**Atomic service API**: This API can be used in atomic services since API version 12. 25 26**System capability**: SystemCapability.ArkUI.ArkUI.Full 27 28| Name | Type | Mandatory | Description | 29| -------- | -------- | -------- | -------- | 30| type |[window.AvoidAreaType](./js-apis-window.md#avoidareatype7) | Yes | Type of the area. | 31 32**Return value** 33 34| Type | Description | 35| -------- | -------- | 36|[window.AvoidArea](./js-apis-window.md#avoidarea7) | Area where the window cannot be displayed. | 37 38**Error codes** 39 40For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 41 42| ID | Error Message | 43| ------- | -------- | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 45 46**Example** 47 48```ts 49// ExtensionProvider.ts 50import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 51import { window } from '@kit.ArkUI'; 52 53export default class EntryAbility extends EmbeddedUIExtensionAbility { 54 onSessionCreate(want: Want, session: UIExtensionContentSession) { 55 const extensionWindow = session.getUIExtensionWindowProxy(); 56 // Obtain the information about the area where the window cannot be displayed. 57 let avoidArea: window.AvoidArea | undefined = extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM); 58 console.info(`avoidArea: ${JSON.stringify(avoidArea)}`); 59 } 60} 61``` 62 63### on('avoidAreaChange') 64 65on(type: 'avoidAreaChange', callback: Callback<AvoidAreaInfo>): void 66 67Subscribes to the event indicating changes to the area where the window cannot be displayed. 68 69**Atomic service API**: This API can be used in atomic services since API version 12. 70 71**System capability**: SystemCapability.ArkUI.ArkUI.Full 72 73| Name | Type | Mandatory | Description | 74| ------ | ---- | ---- | ---- | 75| type | string | Yes | Event type. The value is fixed at **'avoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed. | 76| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[AvoidAreaInfo](#avoidareainfo)> | Yes | Callback used to return the area information. | 77 78**Error codes** 79 80For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 81 82| ID | Error Message | 83| ------- | -------- | 84| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 85 86**Example** 87 88```ts 89// ExtensionProvider.ts 90import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 91import { uiExtension } from '@kit.ArkUI'; 92 93export default class EntryAbility extends EmbeddedUIExtensionAbility { 94 onSessionCreate(want: Want, session: UIExtensionContentSession) { 95 const extensionWindow = session.getUIExtensionWindowProxy(); 96 // Subscribe to the event indicating changes to the area where the window cannot be displayed. 97 extensionWindow.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => { 98 console.info(`The avoid area of the host window is: ${JSON.stringify(info.area)}.`); 99 }); 100 } 101} 102``` 103 104### off('avoidAreaChange') 105 106off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaInfo>): void 107 108Unsubscribes from the event indicating changes to the area where the window cannot be displayed. 109 110**Atomic service API**: This API can be used in atomic services since API version 12. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114| Name | Type | Mandatory | Description | 115| -------- | ---- | ---- | --- | 116| type | string | Yes | Event type. The value is fixed at **'avoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed. | 117| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[AvoidAreaInfo](#avoidareainfo)> | No | Callback used for unsubscription. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. | 118 119**Error codes** 120 121For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 122 123| ID | Error Message | 124| -------- | ------------------------------------------------------------ | 125| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 126 127**Example** 128 129```ts 130// ExtensionProvider.ts 131import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 132 133export default class EntryAbility extends EmbeddedUIExtensionAbility { 134 onSessionDestroy(session: UIExtensionContentSession) { 135 const extensionWindow = session.getUIExtensionWindowProxy(); 136 // Cancel all subscriptions to the event indicating changes to the area where the window cannot be displayed. 137 extensionWindow.off('avoidAreaChange'); 138 } 139} 140``` 141 142### on('windowSizeChange') 143 144on(type: 'windowSizeChange', callback: Callback<window.Size>): void 145 146Subscribes to the window size change event of the host application. 147 148**Atomic service API**: This API can be used in atomic services since API version 12. 149 150**System capability**: SystemCapability.ArkUI.ArkUI.Full 151 152| Name | Type | Mandatory | Description | 153| -------- | --------------------- | ---- | ---------------------- | 154| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event. | 155| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[window.Size](js-apis-window.md#size7)> | Yes | Callback used to return the window size. | 156 157**Error codes** 158 159For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 160 161| ID | Error Message | 162| ------- | -------- | 163| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 164 165**Example** 166 167```ts 168// ExtensionProvider.ts 169import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 170import { window } from '@kit.ArkUI'; 171 172export default class EntryAbility extends EmbeddedUIExtensionAbility { 173 onSessionCreate(want: Want, session: UIExtensionContentSession) { 174 const extensionWindow = session.getUIExtensionWindowProxy(); 175 // Subscribe to the window size change event of the host application. 176 extensionWindow.on('windowSizeChange', (size: window.Size) => { 177 console.info(`The avoid area of the host window is: ${JSON.stringify(size)}.`); 178 }); 179 } 180} 181``` 182 183### off('windowSizeChange') 184 185off(type: 'windowSizeChange', callback?: Callback<window.Size>): void 186 187Unsubscribes from the window size change event of the host application. 188 189**Atomic service API**: This API can be used in atomic services since API version 12. 190 191**System capability**: SystemCapability.ArkUI.ArkUI.Full 192 193| Name | Type | Mandatory | Description | 194| -------- | --------------------- | ---- | ---------------------- | 195| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event. | 196| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[window.Size](js-apis-window.md#size7)> | No | Callback used for unsubscription. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. | 197 198**Error codes** 199 200For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 201 202| ID | Error Message | 203| ------- | -------- | 204| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 205 206**Example** 207 208```ts 209// ExtensionProvider.ts 210import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 211 212export default class EntryAbility extends EmbeddedUIExtensionAbility { 213 onSessionDestroy(session: UIExtensionContentSession) { 214 const extensionWindow = session.getUIExtensionWindowProxy(); 215 // Unsubscribe from the window size change event of the host application. 216 extensionWindow.off('windowSizeChange'); 217 } 218} 219``` 220 221### createSubWindowWithOptions 222 223createSubWindowWithOptions(name: string, subWindowOptions: window.SubWindowOptions): Promise<window.Window> 224 225Creates a subwindow for this window proxy. This API uses a promise to return the result. 226 227**System capability**: SystemCapability.ArkUI.ArkUI.Full 228 229**Atomic service API**: This API can be used in atomic services since API version 12. 230 231**Model restriction**: This API can be used only in the stage model. 232 233**Parameters** 234 235| Name | Type | Mandatory | Description | 236| ------ | ------ | ---- | -------------- | 237| name | string | Yes | Name of the subwindow. | 238| subWindowOptions | [window.SubWindowOptions](js-apis-window.md#subwindowoptions11) | Yes | Parameters used for creating the subwindow. | 239 240**Return value** 241 242| Type | Description | 243| -------------------------------- | ------------------------------------------------ | 244| Promise<[window.Window](js-apis-window.md#window)> | Promise used to return the subwindow created. | 245 246**Error codes** 247 248For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). and [Window Error Codes](errorcode-window.md). 249 250| ID | Error Message | 251| ------- | ------------------------------ | 252| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 253| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 254| 1300002 | This window state is abnormal. | 255| 1300005 | This window proxy is abnormal. | 256 257**Example:** 258 259```ts 260// ExtensionProvider.ts 261import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 262import { window } from '@kit.ArkUI'; 263import { BusinessError } from '@kit.BasicServicesKit'; 264 265export default class EntryAbility extends EmbeddedUIExtensionAbility { 266 onSessionCreate(want: Want, session: UIExtensionContentSession) { 267 const extensionWindow = session.getUIExtensionWindowProxy(); 268 const subWindowOpts: window.SubWindowOptions = { 269 title: 'This is a subwindow', 270 decorEnabled: true 271 }; 272 // Create a subwindow. 273 extensionWindow.createSubWindowWithOptions('subWindowForHost', subWindowOpts) 274 .then((subWindow: window.Window) => { 275 subWindow.setUIContent('pages/Index', (err, data) =>{ 276 if (err && err.code != 0) { 277 return; 278 } 279 subWindow?.resize(300, 300, (err, data)=>{ 280 if (err && err.code != 0) { 281 return; 282 } 283 subWindow?.moveWindowTo(100, 100, (err, data)=>{ 284 if (err && err.code != 0) { 285 return; 286 } 287 subWindow?.showWindow((err, data) => { 288 if (err && err.code == 0) { 289 console.info(`The subwindow has been shown!`); 290 } else { 291 console.error(`Failed to show the subwindow!`); 292 } 293 }); 294 }); 295 }); 296 }); 297 }).catch((error: BusinessError) => { 298 console.error(`Create subwindow failed: ${JSON.stringify(error)}`); 299 }) 300 } 301} 302``` 303 304## AvoidAreaInfo 305 306Describes the information about the area where the window cannot be displayed. 307 308**Atomic service API**: This API can be used in atomic services since API version 12. 309 310**System capability**: SystemCapability.ArkUI.ArkUI.Full 311 312| Name | Type | Mandatory | Description | 313| ------ | -------------------- | ------------------ | ------------------ | 314| type | [window.AvoidAreaType](js-apis-window.md#avoidareatype7) | Yes | Type of the area where the window cannot be displayed. | 315| area | [window.AvoidArea](js-apis-window.md#avoidarea7) | Yes| Area where the window cannot be displayed. | 316 317 318## Example 319 320This example shows how to use all the available APIs in the EmbeddedUIExtensionAbility. The bundle name of the sample application is **com.example.embeddeddemo**, and the EmbeddedUIExtensionAbility to start is **ExampleEmbeddedAbility**. 321 322- The EntryAbility (UIAbility) of the sample application loads the **pages/Index.ets** file, whose content is as follows: 323 324 ```ts 325 // The UIAbility loads pages/Index.ets when started. 326 import { Want } from '@kit.AbilityKit'; 327 328 @Entry 329 @Component 330 struct Index { 331 @State message: string = 'Message: ' 332 private want: Want = { 333 bundleName: "com.example.embeddeddemo", 334 abilityName: "ExampleEmbeddedAbility", 335 } 336 337 build() { 338 Row() { 339 Column() { 340 Text(this.message).fontSize(30) 341 EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) 342 .width('100%') 343 .height('90%') 344 .onTerminated((info)=>{ 345 this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); 346 }) 347 .onError((error)=>{ 348 this.message = 'Error: code = ' + error.code; 349 }) 350 } 351 .width('100%') 352 } 353 .height('100%') 354 } 355 } 356 ``` 357 358- The EmbeddedUIExtensionAbility to start by the **\<EmbeddedComponent>** is implemented in the **ets/extensionAbility/ExampleEmbeddedAbility** file. The file content is as follows: 359 360 ```ts 361 import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 362 363 const TAG: string = '[ExampleEmbeddedAbility]' 364 export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility { 365 366 onCreate() { 367 console.info(TAG, `onCreate`); 368 } 369 370 onForeground() { 371 console.info(TAG, `onForeground`); 372 } 373 374 onBackground() { 375 console.info(TAG, `onBackground`); 376 } 377 378 onDestroy() { 379 console.info(TAG, `onDestroy`); 380 } 381 382 onSessionCreate(want: Want, session: UIExtensionContentSession) { 383 console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`); 384 let param: Record<string, UIExtensionContentSession> = { 385 'session': session 386 }; 387 let storage: LocalStorage = new LocalStorage(param); 388 session.loadContent('pages/extension', storage); 389 } 390 } 391 ``` 392 393- The entry page file of the EmbeddedUIExtensionAbility is **pages/extension.ets**, whose content is as follows: 394 395 ```ts 396 import { UIExtensionContentSession } from '@kit.AbilityKit'; 397 import { uiExtension, window } from '@kit.ArkUI'; 398 import { BusinessError } from '@kit.BasicServicesKit'; 399 let storage = LocalStorage.getShared() 400 401 @Entry(storage) 402 @Component 403 struct Extension { 404 @State message: string = 'EmbeddedUIExtensionAbility Index'; 405 private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session'); 406 private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy(); 407 private subWindow: window.Window | undefined = undefined; 408 409 aboutToAppear(): void { 410 this.extensionWindow?.on('windowSizeChange', (size: window.Size) => { 411 console.info(`size = ${JSON.stringify(size)}`); 412 }); 413 this.extensionWindow?.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => { 414 console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`); 415 }); 416 } 417 418 aboutToDisappear(): void { 419 this.extensionWindow?.off('windowSizeChange'); 420 this.extensionWindow?.off('avoidAreaChange'); 421 } 422 423 build() { 424 Column() { 425 Text(this.message) 426 .fontSize(20) 427 .fontWeight(FontWeight.Bold) 428 Button("Obtain Avoid Area Info").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => { 429 let avoidArea: window.AvoidArea | undefined = this.extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM); 430 console.info(`System avoid area: ${JSON.stringify(avoidArea)}`); 431 }) 432 Button("Create Subwindow").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => { 433 let subWindowOpts: window.SubWindowOptions = { 434 'title': 'This is a subwindow', 435 decorEnabled: true 436 }; 437 this.extensionWindow?.createSubWindowWithOptions('subWindowForHost', subWindowOpts) 438 .then((subWindow: window.Window) => { 439 this.subWindow = subWindow; 440 this.subWindow.loadContent('pages/Index', storage, (err, data) =>{ 441 if (err && err.code != 0) { 442 return; 443 } 444 this.subWindow?.resize(300, 300, (err, data)=>{ 445 if (err && err.code != 0) { 446 return; 447 } 448 this.subWindow?.moveWindowTo(100, 100, (err, data)=>{ 449 if (err && err.code != 0) { 450 return; 451 } 452 this.subWindow?.showWindow((err, data) => { 453 if (err && err.code == 0) { 454 console.info(`The subwindow has been shown!`); 455 } else { 456 console.error(`Failed to show the subwindow!`); 457 } 458 }); 459 }); 460 }); 461 }); 462 }).catch((error: BusinessError) => { 463 console.error(`Create subwindow failed: ${JSON.stringify(error)}`); 464 }) 465 }) 466 }.width('100%').height('100%') 467 } 468 } 469 ``` 470 471- Add an item to **extensionAbilities** in the **module.json5** file of the sample application. The details are as follows: 472 ```json 473 { 474 "name": "ExampleEmbeddedAbility", 475 "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets", 476 "type": "embeddedUI" 477 } 478 ``` 479