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