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