鸿蒙NEXT开发：ArkUI框架UI界面-@ohos.arkui.uiExtension (uiExtension)
往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）[*] 鸿蒙开发焦点知识点，看这篇文章就够了
[*] 最新版！鸿蒙HarmonyOS Next应用开发实战学习门路
[*] 鸿蒙HarmonyOS NEXT开发技术最全学习门路指南
[*] 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）
@ohos.arkui.uiExtension (uiExtension)
用于EmbeddedUIExtensionAbility（或UIExtensionAbility）中获取宿主应用的窗口信息或对应的EmbeddedComponent组件的信息。
说明
从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
导入模块
import { uiExtension } from '@kit.ArkUI' WindowProxy
属性
体系本事： SystemCapability.ArkUI.ArkUI.Full
名称范例只读可选说明properties14+WindowProxyProperties否否 组件（EmbeddedComponent或UIExtensionComponent）的信息。
元服务API： 从API version 14开始，该接口支持在元服务中使用。
束缚： 由于架构束缚，不发起在onSessionCreate阶段同步获取该值，发起在收到on('windowSizeChange')回调之后获取。
getWindowAvoidArea
getWindowAvoidArea(type: window.AvoidAreaType): window.AvoidArea
获取宿主应用窗口内容规避的地区；如体系栏地区、刘海屏地区、手势地区、软键盘地区等与宿主窗口内容重叠时，需要宿主窗口内容避让的地区。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
参数名范例必填说明typewindow.AvoidAreaType是表示规避区范例。 返回值：
范例说明window.AvoidArea宿主窗口内容规避地区。 错误码：
以下错误码详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. 示例
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 获取宿主应用窗口的避让信息
let avoidArea: window.AvoidArea | undefined = extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
console.info(`avoidArea: ${JSON.stringify(avoidArea)}`);
}
} on('avoidAreaChange')
on(type: 'avoidAreaChange', callback: Callback<AvoidAreaInfo>): void
注册体系规避区变化的监听。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
参数名范例必填说明typestring是监听的事件范例，固定为'avoidAreaChange'，即体系规避区变化事件。callbackCallback<AvoidAreaInfo>是回调函数：入参用于吸收当前规避区的信息。 错误码：
以下错误码详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. 示例
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
import { uiExtension } from '@kit.ArkUI';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注册避让区变化的监听
extensionWindow.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => {
console.info(`The avoid area of the host window is: ${JSON.stringify(info.area)}.`);
});
}
} off('avoidAreaChange')
off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaInfo>): void
注销体系规避区变化的监听。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
参数名范例必填说明typestring是注销的事件范例，固定为'avoidAreaChange'，即体系规避区变化事件。callbackCallback<AvoidAreaInfo>否回调函数：如果传入该参数，则关闭该监听。如果未传入参数，则关闭所有体系规避区变化的监听。 错误码：
以下错误码详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. 示例
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionDestroy(session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注销所有避让区变化的监听
extensionWindow.off('avoidAreaChange');
}
} on('windowSizeChange')
on(type: 'windowSizeChange', callback: Callback<window.Size>): void
注册宿主应用窗口尺寸变化的监听。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
参数名范例必填说明typestring是监听的事件范例，固定为'windowSizeChange'，即窗口尺寸变化事件。callbackCallback<window.Size>是回调函数：入参用于吸收当前窗口的尺寸。 错误码：
以下错误码详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. 示例
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注册宿主应用窗口大小变化的监听
extensionWindow.on('windowSizeChange', (size: window.Size) => {
console.info(`The avoid area of the host window is: ${JSON.stringify(size)}.`);
});
}
} off('windowSizeChange')
off(type: 'windowSizeChange', callback?: Callback<window.Size>): void
注销宿主应用窗口尺寸变化的监听。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
参数名范例必填说明typestring是注销的事件范例，固定值：'windowSizeChange'，即窗口尺寸变化事件。callbackCallback<window.Size>否回调函数：如果传入该参数，则关闭该监听。如果未传入参数，则关闭所有体系规避区变化的监听。 错误码：
以下错误码详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. 示例
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionDestroy(session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注销宿主应用窗口大小变化的监听
extensionWindow.off('windowSizeChange');
}
} on('rectChange')14+
on(type: 'rectChange', reasons: number, callback: Callback<RectChangeOptions>): void
注册组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听，现在仅支持在2in1设备上使用。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 14开始，该接口支持在元服务中使用。
参数：
参数名范例必填说明typestring是监听事件，固定为'rectChange'，即组件（EmbeddedComponent或UIExtensionComponent）矩形变化事件。reasonsnumber是触发组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的原因。callbackCallback<RectChangeOptions>是回调函数。返回当前组件（EmbeddedComponent或UIExtensionComponent）矩形变化值及变化原因。 错误码：
以下错误码的详细先容。
错误码ID错误信息401Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.801Capability not supported. Failed to call the API due to limited device capabilities. 示例：
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
import { uiExtension } from '@kit.ArkUI';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注册组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听
extensionWindow.on('rectChange', uiExtension.RectChangeReason.HOST_WINDOW_RECT_CHANGE, (data: uiExtension.RectChangeOptions) => {
console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data));
});
}
} off('rectChange')14+
off(type: 'rectChange', callback?: Callback<RectChangeOptions>): void
注销组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听，现在仅支持在2in1设备上使用。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 14开始，该接口支持在元服务中使用。
参数：
参数名范例必填说明typestring是监听事件，固定为'rectChange'，即组件（EmbeddedComponent或UIExtensionComponent）矩形变化事件。callbackCallback<RectChangeOptions>否回调函数。返回当前组件（EmbeddedComponent或UIExtensionComponent）矩形变化值及变化原因。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有组件（EmbeddedComponent或UIExtensionComponent）矩形变化的监听。 错误码：
以下错误码的详细先容。
错误码ID错误信息401Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.801Capability not supported. Failed to call the API due to limited device capabilities. 示例：
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionDestroy(session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
// 注销组件（EmbeddedComponent或UIExtensionComponent）位置及尺寸变化的监听
extensionWindow.off('rectChange');
}
} createSubWindowWithOptions
createSubWindowWithOptions(name: string, subWindowOptions: window.SubWindowOptions): Promise<window.Window>
创建该WindowProxy实例下的子窗口，使用Promise异步回调。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 12开始，该接口支持在元服务中使用。
模子束缚： 此接口仅可在Stage模子下使用。
参数：
参数名范例必填说明namestring是子窗口的名字。subWindowOptionswindow.SubWindowOptions是子窗口参数。 返回值：
范例说明Promise<window.Window>Promise对象。返回当前WindowProxy下创建的子窗口对象。 错误码：
以下错误码的详细先容。
错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.801Capability not supported. Failed to call the API due to limited device capabilities.1300002This window state is abnormal.1300005This window proxy is abnormal. 示例：
// ExtensionProvider.ts
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends EmbeddedUIExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
const extensionWindow = session.getUIExtensionWindowProxy();
const subWindowOpts: window.SubWindowOptions = {
title: 'This is a subwindow',
decorEnabled: true
};
// 创建子窗口
extensionWindow.createSubWindowWithOptions('subWindowForHost', subWindowOpts)
.then((subWindow: window.Window) => {
subWindow.setUIContent('pages/Index', (err, data) =>{
if (err && err.code != 0) {
return;
}
subWindow?.resize(300, 300, (err, data)=>{
if (err && err.code != 0) {
return;
}
subWindow?.moveWindowTo(100, 100, (err, data)=>{
if (err && err.code != 0) {
return;
}
subWindow?.showWindow((err, data) => {
if (err && err.code == 0) {
console.info(`The subwindow has been shown!`);
} else {
console.error(`Failed to show the subwindow!`);
}
});
});
});
});
}).catch((error: BusinessError) => {
console.error(`Create subwindow failed: ${JSON.stringify(error)}`);
})
}
} AvoidAreaInfo
用于表示窗口规避区的信息。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本事：SystemCapability.ArkUI.ArkUI.Full
名称范例必填说明typewindow.AvoidAreaType是窗口规避区范例。areawindow.AvoidArea是窗口内容规避地区。 WindowProxyProperties14+
用于表示组件的干系信息。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 14开始，该接口支持在元服务中使用。
名称范例必填说明uiExtensionHostWindowProxyRectwindow.Rect是组件（EmbeddedComponent或UIExtensionComponent）的位置和宽高。 RectChangeReason14+
组件（EmbeddedComponent或UIExtensionComponent）矩形（位置及尺寸）变化的原因。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 14开始，该接口支持在元服务中使用。
名称值说明HOST_WINDOW_RECT_CHANGE1组件所在的宿主窗口矩形变化。 RectChangeOptions14+
组件（EmbeddedComponent或UIExtensionComponent）矩形（位置及尺寸）变化返回的值及变化原因。
体系本事： SystemCapability.ArkUI.ArkUI.Full
元服务API： 从API version 14开始，该接口支持在元服务中使用。
名称范例可读可写说明rectwindow.Rect是是组件矩形变化后的值。reasonRectChangeReason是是组件矩形变化的原因。 完备示例
本示例展示文档中所有API在EmbeddedUIExtensionAbility中的基础使用方式，示例应用的bundleName为"com.example.embeddeddemo", 被拉起的EmbeddedUIExtensionAbility为"ExampleEmbeddedAbility"。
[*] 示例应用中的EntryAbility(UIAbility)加载首页文件：pages/Index.ets，此中内容如下：
// pages/Index.ets -- UIAbility启动时加载此页面
import { Want } from '@kit.AbilityKit';
@Entry
@Component
struct Index {
@State message: string = 'Message: '
private want: Want = {
bundleName: "com.example.embeddeddemo",
abilityName: "ExampleEmbeddedAbility",
}
build() {
Row() {
Column() {
Text(this.message).fontSize(30)
EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
.width('100%')
.height('90%')
.onTerminated((info)=>{
this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
})
.onError((error)=>{
this.message = 'Error: code = ' + error.code;
})
}
.width('100%')
}
.height('100%')
}
}
[*] EmbeddedComponent拉起的EmbeddedUIExtensionAbility在ets/extensionAbility/ExampleEmbeddedAbility文件中实现，内容如下：
import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
const TAG: string = ''
export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility {
onCreate() {
console.info(TAG, `onCreate`);
}
onForeground() {
console.info(TAG, `onForeground`);
}
onBackground() {
console.info(TAG, `onBackground`);
}
onDestroy() {
console.info(TAG, `onDestroy`);
}
onSessionCreate(want: Want, session: UIExtensionContentSession) {
console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`);
let param: Record<string, UIExtensionContentSession> = {
'session': session
};
let storage: LocalStorage = new LocalStorage(param);
session.loadContent('pages/extension', storage);
}
}
[*] EmbeddedUIExtensionAbility的入口页面文件pages/extension.ets内容如下：
import { UIExtensionContentSession } from '@kit.AbilityKit';
import { uiExtension, window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
let storage = LocalStorage.getShared()
@Entry(storage)
@Component
struct Extension {
@State message: string = 'EmbeddedUIExtensionAbility Index';
private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session');
private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy();
private subWindow: window.Window | undefined = undefined;
aboutToAppear(): void {
this.extensionWindow?.on('windowSizeChange', (size: window.Size) => {
console.info(`size = ${JSON.stringify(size)}`);
});
this.extensionWindow?.on('rectChange', uiExtension.RectChangeReason.HOST_WINDOW_RECT_CHANGE, (data: uiExtension.RectChangeOptions) => {
console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data));
});
this.extensionWindow?.on('avoidAreaChange', (info: uiExtension.AvoidAreaInfo) => {
console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`);
});
}
aboutToDisappear(): void {
this.extensionWindow?.off('windowSizeChange');
this.extensionWindow?.off('rectChange');
this.extensionWindow?.off('avoidAreaChange');
}
build() {
Column() {
Text(this.message)
.fontSize(20)
.fontWeight(FontWeight.Bold)
Button("获取组件大小").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => {
let rect = this.extensionWindow?.properties.uiExtensionHostWindowProxyRect;
console.info(`EmbeddedComponent的位置和尺寸信息: ${JSON.stringify(rect)}`);
})
Button("获取系统规避区信息").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => {
let avoidArea: window.AvoidArea | undefined = this.extensionWindow?.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
console.info(`系统规避区: ${JSON.stringify(avoidArea)}`);
})
Button("创建子窗口").width('90%').margin({top: 5, bottom: 5}).fontSize(16).onClick(() => {
let subWindowOpts: window.SubWindowOptions = {
'title': 'This is a subwindow',
decorEnabled: true
};
this.extensionWindow?.createSubWindowWithOptions('subWindowForHost', subWindowOpts)
.then((subWindow: window.Window) => {
this.subWindow = subWindow;
this.subWindow.loadContent('pages/Index', storage, (err, data) =>{
if (err && err.code != 0) {
return;
}
this.subWindow?.resize(300, 300, (err, data)=>{
if (err && err.code != 0) {
return;
}
this.subWindow?.moveWindowTo(100, 100, (err, data)=>{
if (err && err.code != 0) {
return;
}
this.subWindow?.showWindow((err, data) => {
if (err && err.code == 0) {
console.info(`The subwindow has been shown!`);
} else {
console.error(`Failed to show the subwindow!`);
}
});
});
});
});
}).catch((error: BusinessError) => {
console.error(`Create subwindow failed: ${JSON.stringify(error)}`);
})
})
}.width('100%').height('100%')
}
}
[*] 最后，示例应用的module.json5中的"extensionAbilities"中需要增加一项，具体内容如下：
{
"name": "ExampleEmbeddedAbility",
"srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets",
"type": "embeddedUI"
}
https://i-blog.csdnimg.cn/direct/15ac2b59ab5c4731b627927d56a75698.png
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]