• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 同应用进程嵌入式组件 (EmbeddedComponent)
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @dutie123-->
5<!--Designer: @lmleon-->
6<!--Tester: @fredyuan0912-->
7<!--Adviser: @HelloCrease-->
8
9EmbeddedComponent组件允许当前页面嵌入同一应用内其他EmbeddedUIExtensionAbility供给的UI内容，这些UI运行在独立进程中，提供更高的安全性和稳定性。
10
11EmbeddedComponent组件主要用于实现跨模块、跨进程的嵌入式界面集成，其核心目标是通过模块化设计提升应用的灵活性和用户体验。
12
13开发者在使用时需注意其使用限制和生命周期管理，合理设计应用架构以最大限度地发挥其优势。
14
15## 基本概念
16
17- [EmbeddedComponent](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md)组件
18
19  EmbeddedComponent组件用于在当前页面嵌入本应用内其他EmbeddedUIExtensionAbility提供的UI。它允许开发者将应用的某些功能或界面嵌入另一个界面中，实现更灵活的用户界面设计，适用于需要进程隔离的模块化开发场景。
20
21- [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)组件
22
23  提供方应用中定义使用，用于实现跨进程界面嵌入功能，仅能被同应用的UIAbility拉起，并需在多进程权限的场景下使用。
24
25## 使用约束
26
27- 设备要求
28
29  EmbeddedComponent组件仅支持在拥有多进程权限的设备上使用。
30
31- 应用范围
32
33  EmbeddedComponent组件只能在UIAbility中使用，且被拉起的EmbeddedUIExtensionAbility需与UIAbility属于同一应用。
34
35- 属性限制
36
37  EmbeddedComponent组件支持[通用属性](../reference/apis-arkui/arkui-ts/ts-component-general-attributes.md)，且宽高默认值和最小值均为10vp；
38
39  不支持如下与宽高相关的属性：
40  "constraintSize"、"aspectRatio"、"layoutWeight"、"flexBasis"、"flexGrow"和"flexShrink"。
41
42- 事件调用
43
44  与屏幕坐标相关的事件信息会基于EmbeddedComponent的位置宽高进行坐标转换后传递给被拉起的EmbeddedUIExtensionAbility处理。
45
46  EmbeddedComponent组件不支持[点击](../reference/apis-arkui/arkui-ts/ts-universal-events-click.md)等通用事件，仅支持[onTerminated](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md#onterminated)事件和[onError](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md#onerror)事件。
47
48## 场景示例
49
50该示例简单展示了EmbeddedComponent组件和EmbeddedUIExtensionAbility的基础使用方式。
51
52**加载项首页**
53
54加载项首页是EmbeddedComponent组件的宿主页面，负责加载和展示嵌入式UI扩展能力的内容。以下是一个完整的加载项首页实现示例：
55
56```ts
57import { Want } from '@kit.AbilityKit';
58
59@Entry
60@Component
61struct Index {
62  @State message: string = 'Message: '
63  private want: Want = {
64    bundleName: "com.example.embeddeddemo",
65    abilityName: "ExampleEmbeddedAbility",
66  }
67
68  build() {
69    Row() {
70      Column() {
71        Text(this.message).fontSize(30)
72        EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
73          .width('100%')
74          .height('90%')
75          .onTerminated((info) => {
76            // 点击extension页面内的terminateSelfWithResult按钮后触发onTerminated回调，文本框显示如下信息
77            this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
78          })
79          .onError((error) => {
80            // 失败或异常触发onError回调，文本框显示如下报错内容
81            this.message = 'Error: code = ' + error.code;
82          })
83      }
84      .width('100%')
85    }
86    .height('100%')
87  }
88}
89```
90
91在ArkTS项目中，EmbeddedUIExtensionAbility的实现代码通常位于项目的ets/extensionAbility目录下。例如，ExampleEmbeddedAbility.ets文件位于./ets/extensionAbility/目录中。
92
93在实现加载项首页时，开发者需要注意以下几点：
94
95- 多进程模型检测
96
97  在应用启动时，建议检测设备是否已开启多进程模型。如果未开启，应提供明确的错误提示或引导用户开启。
98
99- 异常处理
100
101  通过[onError](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md#onerror)事件处理加载或运行嵌入式能力时可能出现的错误，提升用户体验。
102
103- 生命周期管理
104
105  了解并管理好嵌入式组件的生命周期，确保资源的正确释放和回收。
106
107- 样式配置
108
109  合理配置EmbeddedComponent组件的大小和位置，确保嵌入式界面能够以期望的尺寸和位置显示。
110
111**提供方应用生命周期实现**
112
113提供方应用是指提供嵌入式UI扩展能力的应用。以下是提供方应用生命周期实现的代码示例：
114
115```ts
116import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
117
118const TAG: string = '[ExampleEmbeddedAbility]'
119
120export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility {
121  onCreate() {
122    console.info(TAG, `onCreate`);
123  }
124
125  onForeground() {
126    console.info(TAG, `onForeground`);
127  }
128
129  onBackground() {
130    console.info(TAG, `onBackground`);
131  }
132
133  onDestroy() {
134    console.info(TAG, `onDestroy`);
135  }
136
137  onSessionCreate(want: Want, session: UIExtensionContentSession) {
138    console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`);
139    let param: Record<string, UIExtensionContentSession> = {
140      'session': session
141    };
142    let storage: LocalStorage = new LocalStorage(param);
143    // 加载pages/extension.ets页面内容
144    session.loadContent('pages/extension', storage);
145  }
146
147  onSessionDestroy(session: UIExtensionContentSession) {
148    console.info(TAG, `onSessionDestroy`);
149  }
150}
151```
152
153关键实现说明：
154
155- 生命周期阶段
156
157  onCreate → onForeground：组件初始化到可见的完整流程；
158
159  onBackground → onForeground：前后台切换时的状态迁移；
160
161  onDestroy：组件被宿主主动销毁时的资源回收点。
162
163- 会话管理
164
165  onSessionCreate：创建独立存储上下文并加载UI界面；
166
167  onSessionDestroy：处理会话结束时（如用户主动关闭）的清理操作。
168
169- 上下文传递
170
171  通过LocalStorage实现UIExtensionContentSession的跨组件传递；
172
173  使用loadContent方法绑定ArkTS页面与扩展能力上下文。
174
175**入口页面**
176
177以下提供方应用的入口组件实现，展示了如何使用UIExtensionContentSession会话以及如何通过按钮点击事件退出嵌入式页面并返回结果，该代码文件需要在main_pages.json配置文件中声明使用。
178
179```ts
180import { UIExtensionContentSession } from '@kit.AbilityKit';
181
182@Entry
183@Component
184struct Extension {
185  @State message: string = 'EmbeddedUIExtensionAbility Index';
186  private localStorage: LocalStorage|undefined = this.getUIContext().getSharedLocalStorage();
187  private session: UIExtensionContentSession | undefined = this.localStorage.get<UIExtensionContentSession>('session');
188
189  build() {
190    Column() {
191      Text(this.message)
192        .fontSize(20)
193        .fontWeight(FontWeight.Bold)
194      Button("terminateSelfWithResult").fontSize(20).onClick(() => {
195        // 点击按钮后调用terminateSelfWithResult退出
196        this.session?.terminateSelfWithResult({
197          resultCode: 1,
198          want: {
199            bundleName: "com.example.embeddeddemo",
200            abilityName: "ExampleEmbeddedAbility",
201          }
202        });
203      })
204    }.width('100%').height('100%')
205  }
206}
207```
208
209在实现入口页面时，开发者需要注意以下几点：
210
2111. 会话管理
212
213   正确获取并使用UIExtensionContentSession会话对象，确保与宿主应用的通信正常。
214
2152. 结果返回
216
217   通过terminateSelfWithResult方法向宿主应用返回结果时，需要指定：
218
219   - resultCode：结果代码；
220
221   - want：目标意图，指定结果的接收方。
222
2233. 页面生命周期
224
225   了解并管理好入口页面的生命周期，确保资源的正确释放和回收。
226
2274. 样式配置
228
229   合理配置页面元素的样式，确保界面显示效果符合预期。
230
231**添加配置项**
232
233  为了使嵌入式UI扩展能力正常工作，需要在应用的配置文件中进行相应的设置。
234
235  在module.json5配置文件的"extensionAbilities"标签下增加ExampleEmbeddedAbility配置，以注册ExampleEmbeddedAbility嵌入式UI扩展能力。
236
237```json
238{
239  "name": "ExampleEmbeddedAbility",
240  "srcEntry": "./ets/extensionAbility/ExampleEmbeddedAbility.ets",
241  "type": "embeddedUI"
242}
243```
244
245**预期效果**
246
2471. 启动应用，由于设备默认未开启多进程，会出现报错信息；
248
249   ![zh-cn_image_0000001502261185](figures/zh-cn_image_0000001502261185.jpg)
250
2512. 设备测试开启多进程后重启设备，开启多进程的hdc命令如下：
252
253   ```bash
254   hdc shell param set persist.sys.abilityms.multi_process_model true
255   ```
256
2573. 启动应用，界面显示正常；
258
259   ![zh-cn_image_0000001502261065](figures/zh-cn_image_0000001502261065.jpg)
260
2614. 点击terminateSelfWithResult按钮，提供方内容消失，页面显示onTerminated信息。
262