1# @ohos.arkui.uiExtension (uiExtension)(系统接口)
2
3用于EmbeddedUIExtensionAbility(或UIExtensionAbility)中获取宿主应用的窗口信息或对应的EmbeddedComponent(或UIExtensionComponent)组件的信息。
4
5> **说明**
6>
7> 从API Version 12开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
8>
9> 本文仅介绍当前模块的系统接口,其他公开接口参见[@ohos.arkui.uiExtension (uiExtension)](js-apis-arkui-uiExtension.md)。
10
11## 导入模块
12
13```
14import { uiExtension } from '@kit.ArkUI'
15```
16
17## WindowProxy
18
19### hideNonSecureWindows
20
21hideNonSecureWindows(shouldHide: boolean): Promise\<void>
22
23设置是否隐藏不安全窗口。
24
25> **说明:**
26>
27> 不安全窗口是指可能遮挡EmbeddedComponent(或UIExtensionComponent)组件的窗口,如全局悬浮窗、宿主子窗口和宿主创建的Dialog窗口(不包括系统应用创建的上述类型窗口)。当EmbeddedComponent(或UIExtensionComponent)组件被用来显示敏感操作提示内容时,可以选择隐藏不安全窗口,保护敏感操作提示内容不会被遮挡。当EmbeddedComponent(或UIExtensionComponent)组件不显示或销毁时需要让不安全窗口重新显示。使用CreateModalUIExtension接口创建的UIExtensionComponent会默认隐藏不安全窗口,若要取消隐藏,需要申请ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS权限,并调用本接口将shouldHide设为false。
28
29**系统能力**:SystemCapability.ArkUI.ArkUI.Full
30
31**系统接口**:此接口为系统接口,三方应用不支持调用。
32
33**参数:**
34
35| 参数名      | 类型                      | 必填 | 说明       |
36| ----------- | ------------------------- | ---- | ---------- |
37| shouldHide  | boolean                   | 是   | 指示是否隐藏不安全窗口,true表示隐藏,false表示不隐藏。 |
38
39**返回值:**
40
41| 类型                | 说明                      |
42| ------------------- | ------------------------- |
43| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
44
45**错误码:**
46
47| 错误码ID | 错误信息                          |
48| -------- | --------------------------------- |
49| 202      | Permission verification failed. A non-system application calls a system API. |
50| 401      | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameters types. <br> 3. Parameter verification failed. |
51| 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. |
52| 1300003  | This window manager service works abnormally. |
53
54**示例**
55
56```ts
57// ExtensionProvider.ts
58
59import { UIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
60import { BusinessError } from '@kit.BasicServicesKit';
61
62export default class EntryAbility extends UIExtensionAbility {
63  onSessionCreate(want: Want, session: UIExtensionContentSession) {
64    const extensionHostWindow = session.getUIExtensionHostWindowProxy();
65    // 隐藏非安全窗口
66    extensionHostWindow.hideNonSecureWindows(true).then(()=> {
67      console.log(`Succeeded in hiding the non-secure windows.`);
68    }).catch((err: BusinessError)=> {
69      console.log(`Failed to hide the non-secure windows. Cause:${JSON.stringify(err)}`);
70    })
71  }
72  onSessionDestroy(session: UIExtensionContentSession) {
73    const extensionHostWindow = session.getUIExtensionHostWindowProxy();
74    // 取消隐藏非安全窗口
75    extensionHostWindow.hideNonSecureWindows(false).then(()=> {
76      console.log(`Succeeded in showing the non-secure windows.`);
77    }).catch((err: BusinessError)=> {
78      console.log(`Failed to show the non-secure windows. Cause:${JSON.stringify(err)}`);
79    })
80  }
81}
82```
83
84### setWaterMarkFlag
85
86setWaterMarkFlag(enable: boolean): Promise&lt;void&gt;
87
88为当前窗口添加或删除安全水印标志,使用Promise异步回调。
89> **说明:**
90>
91> 添加安全水印标志后,窗口在前台时会将当前全屏幕覆盖水印。全屏、悬浮窗、分屏等场景下只要有添加了安全水印标志的窗口在前台,就会显示全屏水印。
92
93**系统能力**:SystemCapability.ArkUI.ArkUI.Full
94
95**系统接口**:此接口为系统接口,三方应用不支持调用。
96
97**参数:**
98
99| 参数名 | 类型     | 必填 | 说明                                            |
100| ------ | ------- | --- | ------------------------------------------------ |
101| enable | boolean | 是   | 是否对窗口添加标志位。true表示添加,false表示删除。 |
102
103**返回值:**
104
105| 类型                | 说明                      |
106| ------------------- | ------------------------- |
107| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
108
109**错误码:**
110
111| 错误码ID | 错误信息 |
112| ------- | ---------------------------------------------- |
113| 1300002 | This window state is abnormal.                 |
114| 1300003 | This window manager service works abnormally.  |
115| 1300008 | The operation is on invalid display. |
116
117**示例**
118
119```ts
120// ExtensionProvider.ts
121import { UIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
122import { BusinessError } from '@kit.BasicServicesKit';
123
124export default class EntryAbility extends UIExtensionAbility {
125  onSessionCreate(want: Want, session: UIExtensionContentSession) {
126    const extensionHostWindow = session.getUIExtensionHostWindowProxy();
127    // 添加安全水印标志
128    extensionHostWindow.setWaterMarkFlag(true).then(() => {
129      console.log(`Succeeded in setting water mark flag of window.`);
130    }).catch((err: BusinessError) => {
131      console.log(`Failed to setting water mark flag of window. Cause:${JSON.stringify(err)}`);
132    })
133  }
134  onSessionDestroy(session: UIExtensionContentSession) {
135    const extensionHostWindow = session.getUIExtensionHostWindowProxy();
136    // 删除安全水印标志
137    extensionHostWindow.setWaterMarkFlag(false).then(() => {
138      console.log(`Succeeded in deleting water mark flag of window.`);
139    }).catch((err: BusinessError) => {
140      console.log(`Failed to deleting water mark flag of window. Cause:${JSON.stringify(err)}`);
141    })
142  }
143}
144```
145