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<void> | 无返回结果的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<void> 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<void> | 无返回结果的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