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