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