1# EmbeddedComponent 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @dutie123--> 5<!--Designer: @lmleon--> 6<!--Tester: @fredyuan0912--> 7<!--Adviser: @HelloCrease--> 8 9EmbeddedComponent用于支持在当前页面嵌入本应用内其他[EmbeddedUIExtensionAbility](../../apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)提供的UI。EmbeddedUIExtensionAbility在独立进程中运行，完成页面布局和渲染。 10 11通常用于有进程隔离诉求的模块化开发场景。 12 13> **说明：** 14> 15> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16 17## 使用约束 18 19EmbeddedComponent仅支持在拥有多进程权限的设备上使用。 20 21EmbeddedComponent只能在UIAbility中使用，且被拉起的EmbeddedUIExtensionAbility需与UIAbility属于同一应用。 22 23## 子组件 24 25无 26 27## 接口 28 29EmbeddedComponent(loader: Want, type: EmbeddedType) 30 31**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35**参数：** 36 37| 参数名 | 类型 | 必填 |说明 | 38| --------------------- | ---------------------------------------------------------- | ---- | ------------------------------------ | 39| loader | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 要加载的EmbeddedUIExtensionAbility。 | 40| type | [EmbeddedType](ts-appendix-enums.md#embeddedtype12) | 是 | 提供方的类型。 | 41 42## 属性 43 44支持[通用属性](ts-component-general-attributes.md)。 45 46> **说明：** 47> 48> EmbeddedComponent组件宽高默认值和最小值均为10vp, 不支持如下与宽高相关的属性："constraintSize"、"aspectRatio"、"layoutWeight"、"flexBasis"、"flexGrow"和"flexShrink"。 49 50## 事件 51 52与屏幕坐标相关的事件信息会基于EmbeddedComponent的位置宽高进行坐标转换后传递给被拉起的EmbeddedUIExtensionAbility处理。 53 54不支持[点击](ts-universal-events-click.md)等通用事件。仅支持以下事件： 55 56### onTerminated 57 58onTerminated(callback: Callback<TerminationInfo>) 59 60被拉起的EmbeddedUIExtensionAbility通过调用`terminateSelfWithResult`或者`terminateSelf`正常退出时，触发本回调函数。 61 62**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 63 64**系统能力：** SystemCapability.ArkUI.ArkUI.Full 65 66**参数：** 67 68| 参数名 | 类型 | 必填 | 说明 | 69| ------- | ------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | 70| callback | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<[TerminationInfo](#terminationinfo)> | 是 | 回调函数，入参用于接收EmbeddedUIExtensionAbility的返回结果，类型为[TerminationInfo](#terminationinfo)。 | 71 72> **说明：** 73> 74> - 若EmbeddedUIExtensionAbility通过调用`terminateSelfWithResult`退出，其携带的信息会传给回调函数的入参； 75> - 若EmbeddedUIExtensionAbility通过调用`terminateSelf`退出，上述回调函数的入参中，"code"取默认值"0"，"want"为"undefined"。 76 77### onError 78 79onError(callback: ErrorCallback) 80 81被拉起的EmbeddedUIExtensionAbility在运行过程中发生异常时触发本回调。可通过回调参数中的code、name和message获取错误信息并做处理，业务错误码详细介绍请参见[UIExtension错误码](../errorcode-uiextension.md)。 82 83**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 84 85**系统能力：** SystemCapability.ArkUI.ArkUI.Full 86 87**参数：** 88 89| 参数名 | 类型 | 必填 | 说明 | 90| ------ | ---------------------------------------------------------------------------- | --------- | --------- | 91| callback | [ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 回调函数，入参用于接收异常信息，类型为[BusinessError](../../apis-basic-services-kit/js-apis-base.md#businesserror)，可通过参数中的`code`、`name`和`message`获取错误信息并做处理。 | 92 93> **说明：** 94> 95> 如下情形会触发本回调： 96> - 通知提供方拉起EmbeddedUIExtensionAbility失败。 97> - 通知提供方EmbeddedUIExtensionAbility切后台失败。 98> - 通知提供方销毁EmbeddedUIExtensionAbility失败。 99> - 提供方EmbeddedUIExtensionAbility异常退出。 100> - 在EmbeddedUIExtensionAbility中嵌套使用EmbeddedComponent。 101 102## TerminationInfo 103 104用于表示被拉起的EmbeddedUIExtensionAbility的返回结果。 105 106**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110### 属性 111 112| 名称 | 类型 | 只读 | 可选 | 说明 | 113| ---- | -------------------------| ---- | ---- | ---------------------------------------------------- | 114| code | number | 否 | 否 | 被拉起EmbeddedUIExtensionAbility退出时返回的结果码，返回的结果码由`terminateSelfWithResult`或者`terminateSelf`被调用时传入的数据决定。 | 115| want | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | 否 | 是 | 被拉起EmbeddedUIExtensionAbility退出时返回的数据。 | 116 117## 示例（加载EmbeddedComponent） 118 119本示例展示`EmbeddedComponent`组件和`EmbeddedUIExtensionAbility`的基础使用方式，示例应用的`bundleName`为"com.example.embeddeddemo", 同应用下被拉起的`EmbeddedUIExtensionAbility`为"ExampleEmbeddedAbility"。本示例仅支持在拥有多进程权限的设备上运行，如2in1。 120 121- 示例应用中的`EntryAbility(UIAbility)`加载首页文件`ets/pages/Index.ets`，其中内容如下： 122 123 ```ts 124 import { Want } from '@kit.AbilityKit'; 125 126 @Entry 127 @Component 128 struct Index { 129 @State message: string = 'Message: '; 130 private want: Want = { 131 bundleName: "com.example.embeddeddemo", 132 abilityName: "ExampleEmbeddedAbility", 133 }; 134 135 build() { 136 Row() { 137 Column() { 138 Text(this.message).fontSize(30) 139 EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) 140 .width('100%') 141 .height('90%') 142 .onTerminated((info) => { 143 // 点击extension页面内的terminateSelfWithResult按钮后触发onTerminated回调，文本框显示如下信息 144 this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); 145 }) 146 .onError((error) => { 147 // 失败或异常触发onError回调，文本框显示如下报错内容 148 this.message = 'Error: code = ' + error.code; 149 }) 150 } 151 .width('100%') 152 } 153 .height('100%') 154 } 155 } 156 ``` 157 158- `EmbeddedComponent`拉起的`ExampleEmbeddedAbility(EmbeddedUIExtensionAbility)`在`ets/extensionAbility/ExampleEmbeddedAbility.ets`文件中实现，内容如下： 159 160 ```ts 161 import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 162 163 const TAG: string = '[ExampleEmbeddedAbility]'; 164 165 export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility { 166 onCreate() { 167 console.info(TAG, `onCreate`); 168 } 169 170 onForeground() { 171 console.info(TAG, `onForeground`); 172 } 173 174 onBackground() { 175 console.info(TAG, `onBackground`); 176 } 177 178 onDestroy() { 179 console.info(TAG, `onDestroy`); 180 } 181 182 onSessionCreate(want: Want, session: UIExtensionContentSession) { 183 console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`); 184 let param: Record<string, UIExtensionContentSession> = { 185 'session': session 186 }; 187 let storage: LocalStorage = new LocalStorage(param); 188 // 加载pages/extension.ets页面内容 189 session.loadContent('pages/extension', storage); 190 } 191 192 onSessionDestroy(session: UIExtensionContentSession) { 193 console.info(TAG, `onSessionDestroy`); 194 } 195 } 196 ``` 197 198- `ExampleEmbeddedAbility(EmbeddedUIExtensionAbility)`的入口页面文件`ets/pages/extension.ets`内容如下，同时需要在`resources/base/profile/main_pages.json`文件中配置该页面路径： 199 200 ```ts 201 import { UIExtensionContentSession } from '@kit.AbilityKit'; 202 203 let storage = new LocalStorage(); 204 205 @Entry(storage) 206 @Component 207 struct Extension { 208 @State message: string = 'EmbeddedUIExtensionAbility Index'; 209 private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session'); 210 211 build() { 212 Column() { 213 Text(this.message) 214 .fontSize(20) 215 .fontWeight(FontWeight.Bold) 216 Button("terminateSelfWithResult").fontSize(20).onClick(() => { 217 // 点击按钮后调用terminateSelfWithResult退出 218 this.session?.terminateSelfWithResult({ 219 resultCode: 1, 220 want: { 221 bundleName: "com.example.embeddeddemo", 222 abilityName: "ExampleEmbeddedAbility", 223 } 224 }); 225 }) 226 }.width('100%').height('100%') 227 } 228 } 229 ``` 230 231- 在`module.json5`配置文件的"extensionAbilities"标签下增加`ExampleEmbeddedAbility`配置，其type类型为`embeddedUI`，具体内容如下： 232 ```json 233 { 234 "name": "ExampleEmbeddedAbility", 235 "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets", 236 "type": "embeddedUI" 237 } 238 ``` 239