1# @ohos.arkui.uiExtension (uiExtension) 2 3用于EmbeddedUIExtensionAbility（或UIExtensionAbility）中获取宿主应用的窗口信息或对应的EmbeddedComponent<!--Del-->（或UIExtensionComponent）<!--DelEnd-->组件的信息。 4 5> **说明** 6> 7> 从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9 10## 导入模块 11 12``` 13import { uiExtension } from '@kit.ArkUI' 14``` 15 16## WindowProxy 17 18### 属性 19 20**系统能力：** SystemCapability.ArkUI.ArkUI.Full 21 22| 名称 | 类型 | 只读 | 可选 | 说明 | 23| ------------------------------------| -------------------------------------------------- | ---- | ---- | ------------------------------------------------------------------------------------------------------ | 24| properties<sup>14+</sup> | [WindowProxyProperties](#windowproxyproperties14) | 否 | 否 | 组件（EmbeddedComponent或UIExtensionComponent）的信息。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。<br/>**约束：** 由于架构约束，不建议在[onSessionCreate](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityonsessioncreate)阶段同步获取该值，建议在收到[on('windowSizeChange')](../apis-arkui/js-apis-arkui-uiExtension.md#onwindowsizechange)回调之后获取。 | 25 26### getWindowAvoidArea 27 28getWindowAvoidArea(type: window.AvoidAreaType): window.AvoidArea 29 30获取宿主应用窗口内容规避的区域；如系统栏区域、刘海屏区域、手势区域、软键盘区域等与宿主窗口内容重叠时，需要宿主窗口内容避让的区域。 31 32**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 33 34**系统能力**：SystemCapability.ArkUI.ArkUI.Full 35 36| 参数名 | 类型 | 必填 | 说明 | 37| -------- | -------- | -------- | -------- | 38| type |[window.AvoidAreaType](./js-apis-window.md#avoidareatype7) | 是 | 表示规避区类型。 | 39 40**返回值：** 41 42| 类型 | 说明 | 43| -------- | -------- | 44|[window.AvoidArea](./js-apis-window.md#avoidarea7) | 宿主窗口内容规避区域。 | 45 46**错误码**： 47 48以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 49 50| 错误码ID | 错误信息 | 51| ------- | -------- | 52| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 53 54**示例** 55 56```ts 57// ExtensionProvider.ts 58import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 59import { window } from '@kit.ArkUI'; 60 61export default class EntryAbility extends EmbeddedUIExtensionAbility { 62 onSessionCreate(want: Want, session: UIExtensionContentSession) { 63 const extensionWindow = session.getUIExtensionWindowProxy(); 64 // 获取宿主应用窗口的避让信息 65 let avoidArea: window.AvoidArea | undefined = extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM); 66 console.info(`avoidArea: ${JSON.stringify(avoidArea)}`); 67 } 68} 69``` 70 71### on('avoidAreaChange') 72 73on(type: 'avoidAreaChange', callback: Callback<AvoidAreaInfo>): void 74 75注册系统规避区变化的监听。 76 77**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 78 79**系统能力**：SystemCapability.ArkUI.ArkUI.Full 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ---- | ---- | ---- | 83| type | string | 是 | 监听的事件类型，固定为'avoidAreaChange'，即系统规避区变化事件。 | 84| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[AvoidAreaInfo](#avoidareainfo)> | 是 | 回调函数：入参用于接收当前规避区的信息。 | 85 86**错误码**： 87 88以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 89 90| 错误码ID | 错误信息 | 91| ------- | -------- | 92| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 93 94**示例** 95 96```ts 97// ExtensionProvider.ts 98import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 99import { uiExtension } from '@kit.ArkUI'; 100 101export default class EntryAbility extends EmbeddedUIExtensionAbility { 102 onSessionCreate(want: Want, session: UIExtensionContentSession) { 103 const extensionWindow = session.getUIExtensionWindowProxy(); 104 // 注册避让区变化的监听 105 extensionWindow.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => { 106 console.info(`The avoid area of the host window is: ${JSON.stringify(info.area)}.`); 107 }); 108 } 109} 110``` 111 112### off('avoidAreaChange') 113 114off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaInfo>): void 115 116注销系统规避区变化的监听。 117 118**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 119 120**系统能力**：SystemCapability.ArkUI.ArkUI.Full 121 122| 参数名 | 类型 | 必填 | 说明 | 123| -------- | ---- | ---- | --- | 124| type | string | 是 | 注销的事件类型，固定为'avoidAreaChange'，即系统规避区变化事件。 | 125| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[AvoidAreaInfo](#avoidareainfo)> | 否 | 回调函数：如果传入该参数，则关闭该监听。如果未传入参数，则关闭所有系统规避区变化的监听。 | 126 127**错误码**： 128 129以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 130 131| 错误码ID | 错误信息 | 132| -------- | ------------------------------------------------------------ | 133| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 134 135**示例** 136 137```ts 138// ExtensionProvider.ts 139import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 140 141export default class EntryAbility extends EmbeddedUIExtensionAbility { 142 onSessionDestroy(session: UIExtensionContentSession) { 143 const extensionWindow = session.getUIExtensionWindowProxy(); 144 // 注销所有避让区变化的监听 145 extensionWindow.off('avoidAreaChange'); 146 } 147} 148``` 149 150### on('windowSizeChange') 151 152on(type: 'windowSizeChange', callback: Callback<window.Size>): void 153 154注册宿主应用窗口尺寸变化的监听。 155 156**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 157 158**系统能力**：SystemCapability.ArkUI.ArkUI.Full 159 160| 参数名 | 类型 | 必填 | 说明 | 161| -------- | --------------------- | ---- | ---------------------- | 162| type | string | 是 | 监听的事件类型，固定为'windowSizeChange'，即窗口尺寸变化事件。 | 163| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[window.Size](js-apis-window.md#size7)> | 是 | 回调函数：入参用于接收当前窗口的尺寸。 | 164 165**错误码**： 166 167以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 168 169| 错误码ID | 错误信息 | 170| ------- | -------- | 171| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 172 173**示例** 174 175```ts 176// ExtensionProvider.ts 177import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 178import { window } from '@kit.ArkUI'; 179 180export default class EntryAbility extends EmbeddedUIExtensionAbility { 181 onSessionCreate(want: Want, session: UIExtensionContentSession) { 182 const extensionWindow = session.getUIExtensionWindowProxy(); 183 // 注册宿主应用窗口大小变化的监听 184 extensionWindow.on('windowSizeChange', (size: window.Size) => { 185 console.info(`The avoid area of the host window is: ${JSON.stringify(size)}.`); 186 }); 187 } 188} 189``` 190 191### off('windowSizeChange') 192 193off(type: 'windowSizeChange', callback?: Callback<window.Size>): void 194 195注销宿主应用窗口尺寸变化的监听。 196 197**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 198 199**系统能力**：SystemCapability.ArkUI.ArkUI.Full 200 201| 参数名 | 类型 | 必填 | 说明 | 202| -------- | --------------------- | ---- | ---------------------- | 203| type | string | 是 | 注销的事件类型，固定值：'windowSizeChange'，即窗口尺寸变化事件。 | 204| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[window.Size](js-apis-window.md#size7)> | 否 | 回调函数：如果传入该参数，则关闭该监听。如果未传入参数，则关闭所有系统规避区变化的监听。 | 205 206**错误码**： 207 208以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 209 210| 错误码ID | 错误信息 | 211| ------- | -------- | 212| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 213 214**示例** 215 216```ts 217// ExtensionProvider.ts 218import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 219 220export default class EntryAbility extends EmbeddedUIExtensionAbility { 221 onSessionDestroy(session: UIExtensionContentSession) { 222 const extensionWindow = session.getUIExtensionWindowProxy(); 223 // 注销宿主应用窗口大小变化的监听 224 extensionWindow.off('windowSizeChange'); 225 } 226} 227``` 228 229### on('rectChange')<sup>14+</sup> 230 231on(type: 'rectChange', reasons: number, callback: Callback<RectChangeOptions>): void 232 233注册组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听，目前仅支持在2in1设备上使用。 234 235**系统能力：** SystemCapability.ArkUI.ArkUI.Full 236 237**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 243| type | string | 是 | 监听事件，固定为'rectChange'，即组件（EmbeddedComponent或UIExtensionComponent）矩形变化事件。 | 244| reasons | number | 是 | 触发组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的原因。 245| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[RectChangeOptions](#rectchangeoptions14)> | 是 | 回调函数。返回当前组件（EmbeddedComponent或UIExtensionComponent）矩形变化值及变化原因。 | 246 247**错误码：** 248 249以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 250 251| 错误码ID | 错误信息 | 252| ------- | -------------------------------------------- | 253| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 254| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 255 256**示例：** 257 258```ts 259// ExtensionProvider.ts 260import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 261import { uiExtension } from '@kit.ArkUI'; 262 263export default class EntryAbility extends EmbeddedUIExtensionAbility { 264 onSessionCreate(want: Want, session: UIExtensionContentSession) { 265 const extensionWindow = session.getUIExtensionWindowProxy(); 266 // 注册组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听 267 extensionWindow.on('rectChange', uiExtension.RectChangeReason.HOST_WINDOW_RECT_CHANGE, (data: uiExtension.RectChangeOptions) => { 268 console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data)); 269 }); 270 } 271} 272``` 273 274### off('rectChange')<sup>14+</sup> 275 276off(type: 'rectChange', callback?: Callback<RectChangeOptions>): void 277 278注销组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听，目前仅支持在2in1设备上使用。 279 280**系统能力：** SystemCapability.ArkUI.ArkUI.Full 281 282**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 288| type | string | 是 | 监听事件，固定为'rectChange'，即组件（EmbeddedComponent或UIExtensionComponent）矩形变化事件。 | 289| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback)<[RectChangeOptions](#rectchangeoptions14)> | 否 | 回调函数。返回当前组件（EmbeddedComponent或UIExtensionComponent）矩形变化值及变化原因。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有组件（EmbeddedComponent或UIExtensionComponent）矩形变化的监听。 | 290 291**错误码：** 292 293以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 294 295| 错误码ID | 错误信息 | 296| ------- | -------------------------------------------- | 297| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 298| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 299 300**示例：** 301 302```ts 303// ExtensionProvider.ts 304import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 305 306export default class EntryAbility extends EmbeddedUIExtensionAbility { 307 onSessionDestroy(session: UIExtensionContentSession) { 308 const extensionWindow = session.getUIExtensionWindowProxy(); 309 // 注销组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听 310 extensionWindow.off('rectChange'); 311 } 312} 313``` 314 315### createSubWindowWithOptions 316 317createSubWindowWithOptions(name: string, subWindowOptions: window.SubWindowOptions): Promise<window.Window> 318 319创建该WindowProxy实例下的子窗口，使用Promise异步回调。 320 321**系统能力：** SystemCapability.ArkUI.ArkUI.Full 322 323**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 324 325**模型约束：** 此接口仅可在Stage模型下使用。 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------ | ---- | -------------- | 331| name | string | 是 | 子窗口的名字。 | 332| subWindowOptions | [window.SubWindowOptions](js-apis-window.md#subwindowoptions11) | 是 | 子窗口参数。 | 333 334**返回值：** 335 336| 类型 | 说明 | 337| -------------------------------- | ------------------------------------------------ | 338| Promise<[window.Window](js-apis-window.md#window)> | Promise对象。返回当前WindowProxy下创建的子窗口对象。 | 339 340**错误码：** 341 342以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 343 344| 错误码ID | 错误信息 | 345| ------- | ------------------------------ | 346| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 347| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 348| 1300002 | This window state is abnormal. | 349| 1300005 | This window proxy is abnormal. | 350 351**示例：** 352 353```ts 354// ExtensionProvider.ts 355import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 356import { window } from '@kit.ArkUI'; 357import { BusinessError } from '@kit.BasicServicesKit'; 358 359export default class EntryAbility extends EmbeddedUIExtensionAbility { 360 onSessionCreate(want: Want, session: UIExtensionContentSession) { 361 const extensionWindow = session.getUIExtensionWindowProxy(); 362 const subWindowOpts: window.SubWindowOptions = { 363 title: 'This is a subwindow', 364 decorEnabled: true 365 }; 366 // 创建子窗口 367 extensionWindow.createSubWindowWithOptions('subWindowForHost', subWindowOpts) 368 .then((subWindow: window.Window) => { 369 subWindow.setUIContent('pages/Index', (err, data) =>{ 370 if (err && err.code != 0) { 371 return; 372 } 373 subWindow?.resize(300, 300, (err, data)=>{ 374 if (err && err.code != 0) { 375 return; 376 } 377 subWindow?.moveWindowTo(100, 100, (err, data)=>{ 378 if (err && err.code != 0) { 379 return; 380 } 381 subWindow?.showWindow((err, data) => { 382 if (err && err.code == 0) { 383 console.info(`The subwindow has been shown!`); 384 } else { 385 console.error(`Failed to show the subwindow!`); 386 } 387 }); 388 }); 389 }); 390 }); 391 }).catch((error: BusinessError) => { 392 console.error(`Create subwindow failed: ${JSON.stringify(error)}`); 393 }) 394 } 395} 396``` 397 398### occupyEvents<sup>18+</sup> 399 400occupyEvents(eventFlags: number): Promise<void> 401 402设置组件（EmbeddedComponent或UIExtensionComponent）占用事件，宿主将不响应组件区域内被占用的事件。 403 404**系统能力：** SystemCapability.ArkUI.ArkUI.Full 405 406**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 407 408**参数：** 409 410| 参数名 | 类型 | 必填 | 说明 | 411| ------ | ------ | ---- | -------------- | 412| eventFlags | number | 是 | 占用的事件类型，具体取值可见[EventFlag](#eventflag18)枚举值。 | 413 414**返回值：** 415 416| 类型 | 说明 | 417| ------------------- | ------------------------ | 418| Promise<void> | 无返回结果的Promise对象。 | 419 420**错误码：** 421 422以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 423 424| 错误码ID | 错误信息 | 425| -------- | ------------------------------ | 426| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 427| 1300002 | This window state is abnormal. | 428| 1300003 | This window manager service works abnormally. | 429 430**示例：** 431 432```ts 433// ExtensionProvider.ts 434import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 435import { uiExtension } from '@kit.ArkUI'; 436 437export default class EntryAbility extends EmbeddedUIExtensionAbility { 438 onSessionCreate(want: Want, session: UIExtensionContentSession) { 439 const extensionWindow = session.getUIExtensionWindowProxy(); 440 // 占用事件 441 setTimeout(() => { 442 try { 443 extensionWindow.occupyEvents(uiExtension.EventFlag.EVENT_CLICK | uiExtension.EventFlag.EVENT_LONG_PRESS); 444 } catch (e) { 445 console.error(`Occupy events got exception code: ${e.code}, message: ${e.message}`); 446 } 447 }, 500); 448 } 449} 450``` 451 452## EventFlag<sup>18+</sup> 453 454事件类型枚举。 455 456**系统能力：** SystemCapability.ArkUI.ArkUI.Full 457 458**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 459 460| 名称 | 值 | 说明 | 461|-----------------------------| --------------- |----------------| 462| EVENT_NONE | 0x00000000 | 无事件。 | 463| EVENT_PAN_GESTURE_LEFT | 0x00000001 | 左滑事件。 | 464| EVENT_PAN_GESTURE_RIGHT | 0x00000002 | 右滑事件。 | 465| EVENT_PAN_GESTURE_UP | 0x00000004 | 上滑事件。 | 466| EVENT_PAN_GESTURE_DOWN | 0x00000008 | 下滑事件。 | 467| EVENT_CLICK | 0x00000100 | 点击事件。 | 468| EVENT_LONG_PRESS | 0x00000200 | 长按事件。 | 469 470## AvoidAreaInfo 471 472用于表示窗口规避区的信息。 473 474**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 475 476**系统能力**：SystemCapability.ArkUI.ArkUI.Full 477 478| 名称 | 类型 | 必填 | 说明 | 479| ------ | -------------------- | ------------------ | ------------------ | 480| type | [window.AvoidAreaType](js-apis-window.md#avoidareatype7) | 是 | 窗口规避区类型。 | 481| area | [window.AvoidArea](js-apis-window.md#avoidarea7) | 是| 窗口内容规避区域。 | 482 483## WindowProxyProperties<sup>14+</sup> 484 485用于表示组件的相关信息。 486 487**系统能力：** SystemCapability.ArkUI.ArkUI.Full 488 489**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 490 491| 名称 | 类型 | 必填 | 说明 | 492| ------------------------------ | ----------- | -------------------------------- | -------------------------------- | 493| uiExtensionHostWindowProxyRect | [window.Rect](js-apis-window.md#rect7) | 是 | 组件（EmbeddedComponent或UIExtensionComponent）的位置和宽高。 | 494 495## RectChangeReason<sup>14+</sup> 496 497组件（EmbeddedComponent或UIExtensionComponent）矩形（位置及尺寸）变化的原因。 498 499**系统能力：** SystemCapability.ArkUI.ArkUI.Full 500 501**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 502 503| 名称 | 值 | 说明 | 504| ----------------------- | ------ | ------------------------------------------------------------ | 505| HOST_WINDOW_RECT_CHANGE | 0x0001 | 组件所在的宿主窗口矩形变化。 | 506 507## RectChangeOptions<sup>14+</sup> 508 509组件（EmbeddedComponent或UIExtensionComponent）矩形（位置及尺寸）变化返回的值及变化原因。 510 511**系统能力：** SystemCapability.ArkUI.ArkUI.Full 512 513**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 514 515| 名称 | 类型 | 可读 | 可写 | 说明 | 516| ---------- | ------------- | ---- | ---- | ------------------ | 517| rect | [window.Rect](js-apis-window.md#rect7) | 是 | 是 | 组件矩形变化后的值。 | 518| reason | [RectChangeReason](#rectchangereason14) | 是 | 是 | 组件矩形变化的原因。 | 519 520## 完整示例 521 522本示例展示文档中所有API在EmbeddedUIExtensionAbility中的基础使用方式，示例应用的`bundleName`为"com.example.embeddeddemo", 被拉起的`EmbeddedUIExtensionAbility`为"ExampleEmbeddedAbility"。 523 524- 示例应用中的EntryAbility(UIAbility)加载首页文件：`pages/Index.ets`，其中内容如下： 525 526 ```ts 527 // pages/Index.ets -- UIAbility启动时加载此页面 528 import { Want } from '@kit.AbilityKit'; 529 530 @Entry 531 @Component 532 struct Index { 533 @State message: string = 'Message: ' 534 private want: Want = { 535 bundleName: "com.example.embeddeddemo", 536 abilityName: "ExampleEmbeddedAbility", 537 } 538 539 build() { 540 Row() { 541 Column() { 542 Text(this.message).fontSize(30) 543 EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) 544 .width('100%') 545 .height('90%') 546 .onTerminated((info)=>{ 547 this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); 548 }) 549 .onError((error)=>{ 550 this.message = 'Error: code = ' + error.code; 551 }) 552 } 553 .width('100%') 554 } 555 .height('100%') 556 } 557 } 558 ``` 559 560- EmbeddedComponent拉起的EmbeddedUIExtensionAbility在`ets/extensionAbility/ExampleEmbeddedAbility`文件中实现，内容如下： 561 562 ```ts 563 import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 564 565 const TAG: string = '[ExampleEmbeddedAbility]' 566 export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility { 567 568 onCreate() { 569 console.info(TAG, `onCreate`); 570 } 571 572 onForeground() { 573 console.info(TAG, `onForeground`); 574 } 575 576 onBackground() { 577 console.info(TAG, `onBackground`); 578 } 579 580 onDestroy() { 581 console.info(TAG, `onDestroy`); 582 } 583 584 onSessionCreate(want: Want, session: UIExtensionContentSession) { 585 console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`); 586 let param: Record<string, UIExtensionContentSession> = { 587 'session': session 588 }; 589 let storage: LocalStorage = new LocalStorage(param); 590 session.loadContent('pages/extension', storage); 591 } 592 } 593 ``` 594 595- EmbeddedUIExtensionAbility的入口页面文件`pages/extension.ets`内容如下： 596 597 ```ts 598 import { UIExtensionContentSession } from '@kit.AbilityKit'; 599 import { uiExtension, window } from '@kit.ArkUI'; 600 import { BusinessError } from '@kit.BasicServicesKit'; 601 let storage = LocalStorage.getShared() 602 603 @Entry(storage) 604 @Component 605 struct Extension { 606 @State message: string = 'EmbeddedUIExtensionAbility Index'; 607 private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session'); 608 private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy(); 609 private subWindow: window.Window | undefined = undefined; 610 611 aboutToAppear(): void { 612 this.extensionWindow?.on('windowSizeChange', (size: window.Size) => { 613 console.info(`size = ${JSON.stringify(size)}`); 614 }); 615 this.extensionWindow?.on('rectChange', uiExtension.RectChangeReason.HOST_WINDOW_RECT_CHANGE, (data: uiExtension.RectChangeOptions) => { 616 console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data)); 617 }); 618 this.extensionWindow?.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => { 619 console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`); 620 }); 621 } 622 623 aboutToDisappear(): void { 624 this.extensionWindow?.off('windowSizeChange'); 625 this.extensionWindow?.off('rectChange'); 626 this.extensionWindow?.off('avoidAreaChange'); 627 } 628 629 build() { 630 Column() { 631 Text(this.message) 632 .fontSize(20) 633 .fontWeight(FontWeight.Bold) 634 Button("获取组件大小").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => { 635 let rect = this.extensionWindow?.properties.uiExtensionHostWindowProxyRect; 636 console.info(`EmbeddedComponent的位置和尺寸信息: ${JSON.stringify(rect)}`); 637 }) 638 Button("获取系统规避区信息").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => { 639 let avoidArea: window.AvoidArea | undefined = this.extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM); 640 console.info(`系统规避区: ${JSON.stringify(avoidArea)}`); 641 }) 642 Button("创建子窗口").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => { 643 let subWindowOpts: window.SubWindowOptions = { 644 'title': 'This is a subwindow', 645 decorEnabled: true 646 }; 647 this.extensionWindow?.createSubWindowWithOptions('subWindowForHost', subWindowOpts) 648 .then((subWindow: window.Window) => { 649 this.subWindow = subWindow; 650 this.subWindow.loadContent('pages/Index', storage, (err, data) =>{ 651 if (err && err.code != 0) { 652 return; 653 } 654 this.subWindow?.resize(300, 300, (err, data)=>{ 655 if (err && err.code != 0) { 656 return; 657 } 658 this.subWindow?.moveWindowTo(100, 100, (err, data)=>{ 659 if (err && err.code != 0) { 660 return; 661 } 662 this.subWindow?.showWindow((err, data) => { 663 if (err && err.code == 0) { 664 console.info(`The subwindow has been shown!`); 665 } else { 666 console.error(`Failed to show the subwindow!`); 667 } 668 }); 669 }); 670 }); 671 }); 672 }).catch((error: BusinessError) => { 673 console.error(`Create subwindow failed: ${JSON.stringify(error)}`); 674 }) 675 }) 676 }.width('100%').height('100%') 677 } 678 } 679 ``` 680 681- 最后，示例应用的`module.json5`中的"extensionAbilities"中需要增加一项，具体内容如下： 682 ```json 683 { 684 "name": "ExampleEmbeddedAbility", 685 "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets", 686 "type": "embeddedUI" 687 } 688 ``` 689