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&lt;void&gt;
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&lt;void&gt; | 无返回结果的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&lt;window.Window&gt;
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&lt;[window.Window](js-apis-window.md#window)&gt; | 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&lt;void&gt;
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&lt;void&gt; | 无返回结果的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&lt;void&gt;
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&lt;void&gt; | 无返回结果的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