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