• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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**System capability**: SystemCapability.ArkUI.ArkUI.Full
28
29**Parameters**
30
31| Name               | Type                         | Mandatory|Description  |
32| --------------------- | ---------------------------------------------------------- | ---- | ------------------------------------ |
33| loader                | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | EmbeddedUIExtensionAbility to load.|
34| type                  | [EmbeddedType](ts-appendix-enums.md#embeddedtype12)                              | Yes  | Type of the provider.                      |
35
36## Attributes
37
38The [universal attributes](ts-component-general-attributes.md) are supported.
39
40> **NOTE**
41>
42> 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**.
43
44## Events
45
46Event 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.
47
48Universal events, such as the [click event](ts-universal-events-click.md), are not supported. Only the following events are supported.
49
50### onTerminated
51
52onTerminated(callback: Callback<TerminationInfo>)
53
54Called when the started EmbeddedUIExtensionAbility is terminated by calling **terminateSelfWithResult** or **terminateSelf**.
55
56**Atomic service API**: This API can be used in atomic services since API version 12.
57
58**System capability**: SystemCapability.ArkUI.ArkUI.Full
59
60**Parameters**
61
62| Name  | Type  | Mandatory| Description    |
63| -------  | ------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
64| callback | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<[TerminationInfo](#terminationinfo)> | Yes| Callback used to return the result from the EmbeddedUIExtensionAbility.|
65
66> **NOTE**
67>
68> - If the EmbeddedUIExtensionAbility is terminated by calling **terminateSelfWithResult**, the carried information is passed as arguments into the callback function.
69> - 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.
70
71### onError
72
73onError(callback: ErrorCallback)
74
75Called when an error occurs during the running of the started EmbeddedUIExtensionAbility.
76
77**Atomic service API**: This API can be used in atomic services since API version 12.
78
79**System capability**: SystemCapability.ArkUI.ArkUI.Full
80
81**Parameters**
82
83| Name| Type                                                                        | Mandatory                                                                      | Description     |
84| ------ | ---------------------------------------------------------------------------- | --------- | --------- |
85| callback    | [ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes| 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.|
86
87> **NOTE**
88>
89> This callback is called to notify the provider of the following:
90> - The EmbeddedUIExtensionAbility fails to be started.
91> - The EmbeddedUIExtensionAbility fails to be switched to the background.
92> - The EmbeddedUIExtensionAbility fails to be destroyed.
93> - The EmbeddedUIExtensionAbility exits abnormally.
94> - An **EmbeddedComponent** is nested in the EmbeddedUIExtensionAbility.
95
96## TerminationInfo
97
98Provides the result returned by the started **EmbeddedUIExtensionAbility**.
99
100**Atomic service API**: This API can be used in atomic services since API version 12.
101
102**System capability**: SystemCapability.ArkUI.ArkUI.Full
103
104### Attributes
105
106| Name| Type                                                      | Mandatory| Description                                                |
107| ---- | ---------------------------------------------------------- | ---- | ---------------------------------------------------- |
108| code | number                                                     | Yes  | Result code returned when the EmbeddedUIExtensionAbility exits.|
109| want | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | No| Data returned when the EmbeddedUIExtensionAbility exits.  |
110
111## Example: Loading an EmbeddedComponent Component
112
113This 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 in the same application is ExampleEmbeddedAbility. This example only supports devices with multi-process permissions, such as 2-in-1 devices.
114
115- The EntryAbility (UIAbility) of the sample application loads the **ets/pages/Index.ets** file, whose content is as follows:
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              // Triggered when the terminateSelfWithResult button is clicked in the extension page.
138              this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
139            })
140            .onError((error) => {
141              // Triggered on failure or exception.
142              this.message = 'Error: code = ' + error.code;
143            })
144        }
145        .width('100%')
146      }
147      .height('100%')
148    }
149  }
150  ```
151
152- The EmbeddedUIExtensionAbility (**ExampleEmbeddedAbility**) to start by the **EmbeddedComponent** is implemented in the **ets/extensionAbility/ExampleEmbeddedAbility.ets** file. The file content is as follows:
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      // Load the pages/extension.ets content.
183      session.loadContent('pages/extension', storage);
184    }
185
186    onSessionDestroy(session: UIExtensionContentSession) {
187      console.log(TAG, `onSessionDestroy`);
188    }
189  }
190  ```
191
192- The entry page file **ets/pages/extension.ets** for **ExampleEmbeddedAbility** (EmbeddedUIExtensionAbility) is as follows. The path to this page must also be configured in the **resources/base/profile/main_pages.json** file.
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          // Call terminateSelfWithResult to exit when the button is clicked.
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- Add the configuration for **ExampleEmbeddedAbility** under the **extensionAbilities** tag in the **module.json5** file. The type is set to **embeddedUI**, as shown below:
226  ```json
227  {
228    "name": "ExampleEmbeddedAbility",
229    "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets",
230    "type": "embeddedUI"
231  }
232  ```
233