• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# EmbeddedUIExtensionAbility
2
3<!--Kit: Ability Kit-->
4<!--Subsystem: Ability-->
5<!--Owner: @zhangyafei-echo-->
6<!--Designer: @zhangyafei-echo-->
7<!--Tester: @lixueqing513-->
8<!--Adviser: @huipeizi-->
9
10## 概述
11
12[EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)是EMBEDDED_UI类型的[ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md)组件，提供了跨进程界面嵌入的能力。
13
14EmbeddedUIExtensionAbility需要和[EmbeddedComponent](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md)一起配合使用，开发者可以在[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的页面中通过EmbeddedComponent嵌入本应用的EmbeddedUIExtensionAbility提供的UI。EmbeddedUIExtensionAbility在独立进程中运行，完成其页面的布局和渲染，与UIAbility数据不互通，适用于有进程隔离诉求的模块化开发场景。
15
16在下面的示例中，UIAbility运行在主进程，其中包含多个EmbeddedComponent。每个EmbeddedComponent对应一个EmbeddedUIExtensionAbility。多个EmbeddedUIExtensionAbility可以分别用于实现办公软件中的文档、表格、演示文件。
17
18**图1** EmbeddedUIExtensionAbility示意图
19
20![embeddeduiextension-intro](figures/embeddeduiextensionability-intro.png)
21
22## 约束限制
23
24当前EmbeddedUIExtensionAbility和EmbeddedComponent仅支持在拥有多进程配置的设备上使用，目前支持多进程配置的设备有2in1与Tablet。
25
26## 生命周期
27
28[EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)提供了onCreate、onSessionCreate、onSessionDestroy、onForeground、onBackground和onDestroy生命周期回调，根据需要重写对应的回调方法。以下生命周期回调均继承自[UIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)。
29
30- **onCreate**：当EmbeddedUIExtensionAbility创建时回调，执行初始化业务逻辑操作。
31- **onSessionCreate**：当EmbeddedUIExtensionAbility界面内容对象创建后调用。
32- **onSessionDestroy**：当EmbeddedUIExtensionAbility界面内容对象销毁后调用。
33- **onForeground**：当EmbeddedUIExtensionAbility从后台转到前台时触发。
34- **onBackground**：当EmbeddedUIExtensionAbility从前台转到后台时触发。
35- **onDestroy**：当EmbeddedUIExtensionAbility销毁时回调，可以执行资源清理等操作。
36
37> **说明：**
38>
39> EmbeddedComponent只能在UIAbility中使用，且被拉起的EmbeddedUIExtensionAbility需与UIAbility属于同一应用。
40>
41> <!--Del-->当前提供的EmbeddedUIExtensionAbility支持多实例场景，并且继承了UIExtensionAbility的进程模型，UIExtensionAbility的多实例及进程配置相关介绍可参见[UIExtensionAbility](uiextensionability.md)。<!--DelEnd-->
42
43EmbeddedUIExtensionAbility通过[UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md)和[UIExtensionContentSession](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md)提供相关能力。本文描述中称被启动的EmbeddedUIExtensionAbility为提供方，称启动EmbeddedUIExtensionAbility的EmbeddedComponent组件为使用方。
44
45## 开发EmbeddedUIExtensionAbility提供方
46
47开发者在实现一个[EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)提供方时，需要在DevEco Studio工程中手动新建一个EmbeddedUIExtensionAbility，具体步骤如下。
48
491. 在工程Module对应的ets目录下，右键选择“New &gt; Directory”，新建一个目录并命名为EmbeddedUIExtAbility。
50
512. 在EmbeddedUIExtAbility目录，右键选择“New &gt; File”，新建一个.ets文件并命名为EmbeddedUIExtAbility.ets。
52
533. 打开EmbeddedUIExtAbility.ets文件，导入EmbeddedUIExtensionAbility的依赖包，自定义类继承EmbeddedUIExtensionAbility并实现onCreate、onSessionCreate、onSessionDestroy、onForeground、onBackground和onDestroy生命周期回调。
54
55    ```ts
56    import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
57
58    const TAG: string = '[ExampleEmbeddedAbility]';
59
60    export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility {
61      onCreate() {
62        console.log(TAG, `onCreate`);
63      }
64
65      onForeground() {
66        console.log(TAG, `onForeground`);
67      }
68
69      onBackground() {
70        console.log(TAG, `onBackground`);
71      }
72
73      onDestroy() {
74        console.log(TAG, `onDestroy`);
75      }
76
77      onSessionCreate(want: Want, session: UIExtensionContentSession) {
78        console.log(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`);
79        let param: Record<string, UIExtensionContentSession> = {
80          'session': session
81        };
82        let storage: LocalStorage = new LocalStorage(param);
83        session.loadContent('pages/extension', storage);
84      }
85
86      onSessionDestroy(session: UIExtensionContentSession) {
87        console.log(TAG, `onSessionDestroy`);
88      }
89    }
90    ```
91
924. EmbeddedUIExtensionAbility的onSessionCreate中加载了入口页面文件pages/extension.ets内容如下：
93
94    ```ts
95    import { UIExtensionContentSession } from '@kit.AbilityKit';
96
97    @Entry()
98    @Component
99    struct Extension {
100      @State message: string = 'EmbeddedUIExtensionAbility Index';
101      localStorage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage();
102      private session: UIExtensionContentSession | undefined = this.localStorage?.get<UIExtensionContentSession>('session');
103
104      build() {
105        Column() {
106          Text(this.message)
107            .fontSize(20)
108            .fontWeight(FontWeight.Bold)
109          Button('terminateSelfWithResult').fontSize(20).onClick(() => {
110            this.session?.terminateSelfWithResult({
111              resultCode: 1,
112              want: {
113                bundleName: 'com.example.embeddeddemo',
114                abilityName: 'ExampleEmbeddedAbility'
115              }});
116          })
117        }.width('100%').height('100%')
118      }
119    }
120    ```
121
1225. 在工程Module对应的[module.json5配置文件](../quick-start/module-configuration-file.md)中注册EmbeddedUIExtensionAbility，type标签需要设置为“embeddedUI”，srcEntry标签表示当前EmbeddedUIExtensionAbility组件所对应的代码路径。
123
124    ```json
125    {
126      "module": {
127        "extensionAbilities": [
128          {
129            "name": "EmbeddedUIExtAbility",
130            "icon": "$media:icon",
131            "description": "EmbeddedUIExtAbility",
132            "type": "embeddedUI",
133            "srcEntry": "./ets/EmbeddedUIExtAbility/EmbeddedUIExtAbility.ets"
134          },
135        ]
136      }
137    }
138    ```
139
140
141
142## 开发EmbeddedUIExtensionAbility使用方
143
144开发者可以在[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的页面中通过[EmbeddedComponent](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md)容器加载自己应用内的[EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md)。此外，EmbeddedUIExtensionAbility在[want](../reference/apis-ability-kit/js-apis-app-ability-want.md).parameters中新增了两个字段ohos.extension.processMode.hostSpecified和ohos.extension.processMode.hostInstance。
145- ohos.extension.processMode.hostSpecified控制非首次启动的EmbeddedUIExtensionAbility是否运行在同[UIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)的进程中，参数是进程名称。例如，"ohos.extension.processMode.hostSpecified"： "com.ohos.inentexecutedemo:share"。
146- ohos.extension.processMode.hostInstance控制启动的EmbeddedUIExtensionAbility是否按照独立进程启动，传入false时，按照UIExtensionAbility的进程模型启动，入参true的时候，不管被拉起的UIExtensionAbility配置的是什么进程模型，都会新增一个进程，例如，"ohos.extension.processMode.hostInstance": "true"。
147
148ohos.extension.processMode.hostSpecified和ohos.extension.processMode.hostInstance同时配置时，hostSpecified优先，会运行在指定的进程中。
149如在首页文件：pages/Index.ets中添加如下内容：
150```ts
151import { Want } from '@kit.AbilityKit';
152import { BusinessError } from '@kit.BasicServicesKit';
153
154@Entry
155@Component
156struct Index {
157  @State message: string = 'Message: '
158  private want: Want = {
159    bundleName: 'com.example.embeddeddemo',
160    abilityName: 'EmbeddedUIExtAbility',
161    parameters: {
162      'ohos.extension.processMode.hostInstance': 'true'
163    }
164  }
165
166  build() {
167    Row() {
168      Column() {
169        Text(this.message).fontSize(30)
170        EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
171          .width('100%')
172          .height('90%')
173          .onTerminated((info: TerminationInfo) => {
174            this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
175          })
176          .onError((error: BusinessError) => {
177            this.message = 'Error: code = ' + error.code;
178          })
179      }
180      .width('100%')
181    }
182    .height('100%')
183  }
184}
185```
186