1# @ohos.uiExtensionHost (系统接口) 2 3仅用于在有进程隔离诉求的UIExtensionComponent组件中为提供方应用提供宿主应用的窗口信息和组件本身的信息。 4 5> **说明** 6> 7> 从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 本模块接口为系统接口。 10 11## 导入模块 12 13``` 14import uiExtensionHost from '@ohos.uiExtensionHost' 15``` 16 17## UIExtensionHostWindowProxyProperties 18 19uiExtensionHostWindowProxyRect: window.Rect 20 21获取UIExtensionComponent的位置和宽高信息。 22 23**系统能力**：SystemCapability.ArkUI.ArkUI.Full 24 25**系统接口**：此接口为系统接口 26 27| 属性名 | 类型 | 说明 | 28| ------------------------------ | ----------- | -------------------------------- | 29| uiExtensionHostWindowProxyRect | [window.Rect](js-apis-window.md) | UIExtensionComponent的位置和宽高。 | 30 31**示例** 32 33```ts 34@Entry(storage) 35@Component 36struct Hello { 37 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 38 private extensionWindowRect = this.extensionWindow.properties.uiExtensionHostWindowProxyRect 39 40 build() { 41 Row() { 42 Column() { 43 Text("Hello world") 44 } 45 .width('100%') 46 } 47 .height('100%') 48 } 49} 50``` 51 52## UIExtensionHostWindowProxy 53 54### getWindowAvoidArea 55 56getWindowAvoidArea(type: window.AvoidAreaType): window.AvoidArea 57 58获取窗口具体避让类型的避让区信息。 59 60**系统能力**：SystemCapability.ArkUI.ArkUI.Full 61 62**系统API**：此接口为系统接口，三方应用不支持调用。 63 64| 参数名 | 类型 | 必填 | 说明 | 65| -------- | -------- | -------- | -------- | 66| type |[window.AvoidAreaType](js-apis-window.md) | 是 | 获取的避让区类型 | 67 68**返回值：** 69 70| 类型 | 说明 | 71| -------- | -------- | 72|[window.AvoidArea](js-apis-window.md) | 避让区信息 | 73 74**示例** 75 76```ts 77@Entry(storage) 78@Component 79struct Hello { 80 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 81 82 build() { 83 Row() { 84 Column() { 85 Button("TYPE_SYSTEM").onClick(() => { 86 if (this.extensionWindow != undefined) { 87 let avoidArea: window.AvoidArea = this.extensionWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM) 88 console.log(`${JSON.stringify(avoidArea)}`) 89 } 90 }) 91 } 92 .width('100%') 93 } 94 .height('100%') 95 } 96} 97``` 98 99### on('avoidAreaChange') 100 101on(type: 'avoidAreaChange', callback: Callback<{ type: window.AvoidAreaType, area: window.AvoidArea }>): void 102 103注册避让区域变更回调方法 104 105**系统能力**：SystemCapability.ArkUI.ArkUI.Full 106 107**系统API**：此接口为系统接口，三方应用不支持调用。 108 109| 参数名 | 类型 | 必填 | 说明 | 110| -------- | ------------------------------------------------------------ | ---- | ---------------------- | 111| type | string | 是 | 注册的回调方法类型说明。 | 112| callback | Callback<{ type: window.AvoidAreaType, area: window.AvoidArea }> | 是 | 注册的回调方法。 | 113 114**示例** 115 116```ts 117@Entry(storage) 118@Component 119struct Hello { 120 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 121 122 aboutToAppear() { 123 this.extensionWindow.on('avoidAreaChange', (avoid) => { 124 console.info(`${JSON.stringify(avoid.type)}`) 125 console.info(`${JSON.stringify(avoid.area)}`) 126 }) 127 } 128 129 build() { 130 Row() { 131 Column() { 132 Text("Hello world") 133 } 134 .width('100%') 135 } 136 .height('100%') 137 } 138} 139``` 140 141### off('avoidAreaChange') 142 143off(type: 'avoidAreaChange', callback?: Callback<{ type: window.AvoidAreaType, area: window.AvoidArea }>): void 144 145注销避让区域变更回调方法 146 147**系统能力**：SystemCapability.ArkUI.ArkUI.Full 148 149**系统API**：此接口为系统接口，三方应用不支持调用。 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------- | ------------------------------------------------------------ | ---- | ---------------------- | 153| type | string | 是 | 注销的回调方法类型说明。 | 154| callback | Callback<{ type: window.AvoidAreaType, area: window.AvoidArea }> | 是 | 注销的回调方法。 | 155 156**示例** 157 158```ts 159@Entry(storage) 160@Component 161struct Hello { 162 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 163 private avoidAreaChangeCallback: Callback<{ type: window.AvoidAreaType, area: window.AvoidArea }> = (avoid) => { 164 console.info(`${JSON.stringify(avoid.area)}`) 165 console.info(`${JSON.stringify(avoid.type)}`) 166 } 167 168 aboutToAppear() { 169 this.extensionWindow.on('avoidAreaChange', this.avoidAreaChangeCallback) 170 } 171 172 build() { 173 Row() { 174 Column() { 175 Button("注销回调").onClick(() => { 176 this.extensionWindow.off('avoidAreaChange', this.avoidAreaChangeCallback) 177 }) 178 } 179 .width('100%') 180 } 181 .height('100%') 182 } 183} 184``` 185 186### on('windowSizeChange') 187 188on(type: 'windowSizeChange', callback: Callback<window.Size>): void 189 190注册窗口信息变更回调方法 191 192**系统能力**：SystemCapability.ArkUI.ArkUI.Full 193 194**系统API**：此接口为系统接口，三方应用不支持调用。 195 196| 参数名 | 类型 | 必填 | 说明 | 197| -------- | --------------------- | ---- | ---------------------- | 198| type | string | 是 | 注册的回调方法类型说明。 | 199| callback | Callback<window.Size> | 是 | 注册的回调方法。 | 200 201**示例** 202 203```ts 204@Entry(storage) 205@Component 206struct Hello { 207 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 208 209 aboutToAppear() { 210 this.extensionWindow.on('windowSizeChange', (size) => { 211 console.info(`${JSON.stringify(size)}`) 212 }) 213 } 214 215 build() { 216 Row() { 217 Column() { 218 Text("Hello world") 219 } 220 .width('100%') 221 } 222 .height('100%') 223 } 224} 225``` 226 227### off('windowSizeChange') 228 229off(type: 'windowSizeChange', callback?: Callback<window.Size>): void 230 231注销窗口信息变更回调方法 232 233**系统能力**：SystemCapability.ArkUI.ArkUI.Full 234 235**系统API**：此接口为系统接口，三方应用不支持调用。 236 237| 参数名 | 类型 | 必填 | 说明 | 238| -------- | --------------------- | ---- | ---------------------- | 239| type | string | 是 | 注销的回调方法类型说明。 | 240| callback | Callback<window.Size> | 是 | 注销的回调方法。 | 241 242**示例** 243 244```ts 245@Entry(storage) 246@Component 247struct Hello { 248 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 249 private windowSizeChangeCallback: Callback<window.Size> = (size) => { 250 console.info(`${JSON.stringify(size)}`) 251 } 252 253 aboutToAppear() { 254 this.extensionWindow.on('windowSizeChange', this.windowSizeChangeCallback) 255 } 256 257 258 build() { 259 Row() { 260 Column() { 261 Button("注销回调").onClick(() => { 262 this.extensionWindow.off('windowSizeChange', this.windowSizeChangeCallback) 263 }) 264 } 265 .width('100%') 266 } 267 .height('100%') 268 } 269} 270``` 271 272### properties 273 274properties: UIExtensionHostWindowProxyProperties 275 276UIExtensionComponent组件以及宿主窗口的信息 277 278**系统能力**：SystemCapability.ArkUI.ArkUI.Full 279 280**系统API**：此接口为系统接口，三方应用不支持调用。 281 282| 参数名 | 类型 | 说明 | 283| ---------- | ------------------------------------ | -------------------------------- | 284| properties | UIExtensionHostWindowProxyProperties | UIExtensionComponent的位置和宽高。 | 285 286**示例** 287 288```ts 289@Entry(storage) 290@Component 291struct Hello { 292 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow') 293 private properties = this.extensionWindow.properties 294 295 build() { 296 Row() { 297 Column() { 298 Text(`UIExtensionWindowRect: ${JSON.stringify(this.properties.uiExtensionHostWindowProxyRect)}`) 299 } 300 .width('100%') 301 } 302 .height('100%') 303 } 304} 305``` 306 307### hideNonSecureWindows 308 309hideNonSecureWindows(shouldHide: boolean): Promise\<void> 310 311设置是否隐藏不安全窗口。 312不安全窗口是指可能遮挡UIExtensionComponent的窗口类型，如非系统全局悬浮窗、宿主子窗口。当UIExtensionComponent组件被用来显示敏感操作提示内容时，可以选择隐藏不安全窗口，保护敏感操作提示内容不会被遮挡。当UIExtensionComponent不显示或销毁时需要让不安全窗口重新显示。 313 314**系统能力**：SystemCapability.ArkUI.ArkUI.Full 315 316**系统API**：此接口为系统接口，三方应用不支持调用。 317 318**参数：** 319 320| 参数名 | 类型 | 必填 | 说明 | 321| ----------- | ------------------------- | ---- | ---------- | 322| shouldHide | boolean | 是 | 指示是否隐藏不安全窗口，true表示隐藏，false表示不隐藏。 | 323 324**返回值：** 325 326| 类型 | 说明 | 327| ------------------- | ------------------------- | 328| Promise<void> | 无返回结果的Promise对象。 | 329 330**示例** 331 332```ts 333import UIExtensionAbility from '@ohos.app.ability.UIExtensionAbility' 334import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession' 335import Want from '@ohos.app.ability.Want'; 336const TAG: string = '[UIExtAbility]' 337export default class UIExtAbility extends UIExtensionAbility { 338 339 onCreate() { 340 console.log(TAG, `UIExtAbility onCreate`) 341 } 342 343 onForeground() { 344 console.log(TAG, `UIExtAbility onForeground`) 345 } 346 347 onBackground() { 348 console.log(TAG, `UIExtAbility onBackground`) 349 } 350 351 onDestroy() { 352 console.log(TAG, `UIExtAbility onDestroy`) 353 } 354 355 onSessionCreate(want: Want, session: UIExtensionContentSession) { 356 console.log(TAG, `UIExtAbility onSessionCreate`) 357 session.loadContent('pages/extension'); 358 359 let extensionHostWindow = session.getUIExtensionHostWindowProxy(); 360 let promise = extensionHostWindow.hideNonSecureWindows(true); 361 promise.then(()=> { 362 console.log(TAG, `Succeeded in hiding the non-secure windows.`); 363 }).catch((err: BusinessError)=> { 364 console.log(TAG, `Failed to hide the non-secure windows. Cause:${JSON.stringify(err)}`); 365 }) 366 } 367 368 onSessionDestroy(session: UIExtensionContentSession) { 369 console.log(TAG, `UIExtAbility onSessionDestroy`) 370 371 let extensionHostWindow = session.getUIExtensionHostWindowProxy(); 372 let promise = extensionHostWindow.hideNonSecureWindows(false); 373 promise.then(()=> { 374 console.log(TAG, `Succeeded in showing the non-secure windows.`); 375 }).catch((err: BusinessError)=> { 376 console.log(TAG, `Failed to show the non-secure windows. Cause:${JSON.stringify(err)}`); 377 }) 378 } 379} 380``` 381 382## 示例 383 384在提供方中应用中，首先通过[UIExtensionContentSession](../apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md)接口获取到UIExtensionHostWindowProxy对象。 385 386```ts 387import UIExtensionAbility from '@ohos.app.ability.UIExtensionAbility' 388import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession' 389import Want from '@ohos.app.ability.Want'; 390const TAG: string = '[UIExtAbility]' 391export default class UIExtAbility extends UIExtensionAbility { 392 393 onCreate() { 394 console.log(TAG, `UIExtAbility onCreate`) 395 } 396 397 onForeground() { 398 console.log(TAG, `UIExtAbility onForeground`) 399 } 400 401 onBackground() { 402 console.log(TAG, `UIExtAbility onBackground`) 403 } 404 405 onDestroy() { 406 console.log(TAG, `UIExtAbility onDestroy`) 407 } 408 409 onSessionCreate(want: Want, session: UIExtensionContentSession) { 410 let extensionHostWindow = session.getUIExtensionHostWindowProxy(); 411 let storage: LocalStorage = new LocalStorage({ 412 'session': session, 413 'extensionWindow': extensionHostWindow 414 }); 415 session.loadContent('pages/extension', storage); 416 } 417 418 onSessionDestroy(session: UIExtensionContentSession) { 419 console.log(TAG, `UIExtAbility onSessionDestroy`) 420 } 421} 422``` 423 424在具体的页面中 425 426```ts 427import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession' 428import uiExtensionHost from '@ohos.uiExtensionHost' 429import window from '@ohos.window' 430 431 432let storage = LocalStorage.getShared() 433 434@Entry(storage) 435@Component 436struct Hello { 437 private extensionWindow: uiExtensionHost.UIExtensionHostWindowProxy | undefined = storage.get<uiExtensionHost.UIExtensionHostWindowProxy>('extensionWindow'); 438 439 build() { 440 Row() { 441 Column() { 442 Button("TYPE_SYSTEM").onClick(() => { 443 if (this.extensionWindow != undefined) { 444 let avoidArea: window.AvoidArea = this.extensionWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM) 445 console.log(`${JSON.stringify(avoidArea)}`) 446 } 447 }) 448 Button("TYPE_CUTOUT").onClick(() => { 449 if (this.extensionWindow != undefined) { 450 let avoidArea: window.AvoidArea = this.extensionWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_CUTOUT) 451 console.log(`${JSON.stringify(avoidArea)}`) 452 } 453 }) 454 } 455 .width('100%') 456 } 457 .height('100%') 458 } 459} 460```