1# EmbeddedComponent
2
3The **EmbeddedComponent** is a component used to embed into the current page the UI provided by another [EmbeddedUIExtensionAbility](../../apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) in the same application. The EmbeddedUIExtensionAbility runs in an independent process for UI layout and rendering.
4
5It is usually used in modular development scenarios where process isolation is required.
6
7> **NOTE**
8>
9> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
10
11## Constraints
12
13The **EmbeddedComponent** is supported only on devices configured with multi-process permissions.
14
15The **EmbeddedComponent** can be used only in the UIAbility, and the EmbeddedUIExtensionAbility to start must belong to the same application as the UIAbility.
16
17## Child Components
18
19Not supported
20
21## APIs
22
23EmbeddedComponent(loader: Want, type: EmbeddedType)
24
25**Atomic service API**: This API can be used in atomic services since API version 12.
26
27**Parameters**
28
29| Name               | Type                                                  | Mandatory| Description                            |
30| --------------------- | ---------------------------------------------------------- | ---- | ------------------------------------ |
31| loader                | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | EmbeddedUIExtensionAbility to load.|
32| type                  | [EmbeddedType](ts-appendix-enums.md#embeddedtype12)                              | Yes  | Type of the provider.                      |
33
34## Attributes
35
36The [universal attributes](ts-universal-attributes-size.md) are supported.
37
38> **NOTE**
39>
40> The default and minimum widths and heights of the **EmbeddedComponent** are all 10 vp. The following attributes related to the width and height are not supported: **constraintSize**, **aspectRatio**, **layoutWeight**, **flexBasis**, **flexGrow**, and **flexShrink**.
41
42## Events
43
44Event information related to screen coordinates is converted based on the position, width, and height of the **EmbeddedComponent**, before being transferred to the EmbeddedUIExtensionAbility for processing.
45
46The [universal events](ts-universal-events-click.md) are not supported. Only the following events are supported.
47
48### onTerminated
49
50onTerminated(callback: Callback<TerminationInfo>)
51
52Called when the started EmbeddedUIExtensionAbility is terminated by calling **terminateSelfWithResult** or **terminateSelf**.
53
54**Atomic service API**: This API can be used in atomic services since API version 12.
55
56**Parameters**
57
58| Name  | Type  | Description                                                                                    |
59| -------  | ------ | ---------------------------------------------------------------------------------------- |
60| callback | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<[TerminationInfo](#terminationinfo)> | Callback used to return the result from the EmbeddedUIExtensionAbility.|
61
62> **NOTE**
63>
64> - If the EmbeddedUIExtensionAbility is terminated by calling **terminateSelfWithResult**, the carried information is passed as arguments into the callback function.
65> - If the EmbeddedUIExtensionAbility is terminated by calling **terminateSelf**, the input parameters **code** and **want** in the callback function are at their default values: **0** and **undefined**, respectively.
66
67### onError
68
69onError(callback: ErrorCallback)
70
71Called when an error occurs during the running of the started EmbeddedUIExtensionAbility.
72
73**Atomic service API**: This API can be used in atomic services since API version 12.
74
75**Parameters**
76
77| Name| Type                                                                        | Description     |
78| ------ | ---------------------------------------------------------------------------- | --------- |
79| callback    | [ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback) | Callback used to return the error information of the [BusinessError](../../apis-basic-services-kit/js-apis-base.md#businesserror) type. The error information can be obtained and processed based on the **code**, **name**, and **message** parameters.|
80
81> **NOTE**
82>
83> This callback is called to notify the provider of the following:
84> - The EmbeddedUIExtensionAbility fails to be started.
85> - The EmbeddedUIExtensionAbility fails to be switched to the background.
86> - The EmbeddedUIExtensionAbility fails to be destroyed.
87> - The EmbeddedUIExtensionAbility exits abnormally.
88> - An **EmbeddedComponent** is nested in the EmbeddedUIExtensionAbility.
89
90## TerminationInfo
91
92Provides the result returned by the started **EmbeddedUIExtensionAbility**.
93
94**Atomic service API**: This API can be used in atomic services since API version 12.
95
96| Name | Type  | Description                                                |
97| ------- | ------ | ---------------------------------------------------  |
98| code    | number | Result code returned when the EmbeddedUIExtensionAbility exits.|
99| want    | [Want](../../apis-ability-kit/js-apis-app-ability-want.md)   | Data returned when the EmbeddedUIExtensionAbility exits.  |
100
101## Example
102
103This example shows the basic usage of the **EmbeddedComponent** and EmbeddedUIExtensionAbility. The bundle name of the sample application is **com.example.embeddeddemo**, and the started EmbeddedUIExtensionAbility is ExampleEmbeddedAbility.
104
105- The EntryAbility (UIAbility) of the sample application loads the **pages/Index.ets** file, whose content is as follows:
106
107  ```ts
108  // The UIAbility loads pages/Index.ets when started.
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- The EmbeddedUIExtensionAbility started by the **EmbeddedComponent** is implemented in the **ets/extensionAbility/ExampleEmbeddedAbility** file. The file content is as follows:
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- The entry page file of the EmbeddedUIExtensionAbility is **pages/extension.ets**, whose content is as follows:
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- Add an item to **extensionAbilities** in the **module.json5** file of the sample application. The details are as follows:
212  ```json
213  {
214    "name": "ExampleEmbeddedAbility",
215    "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets",
216    "type": "embeddedUI"
217  }
218  ```
219