• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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    @Entry()
83    @Component
84    struct Extension {
85      @State message: string = 'EmbeddedUIExtensionAbility Index';
86      localStorage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage();
87      private session: UIExtensionContentSession | undefined = this.localStorage?.get<UIExtensionContentSession>('session');
88
89      build() {
90        Column() {
91          Text(this.message)
92            .fontSize(20)
93            .fontWeight(FontWeight.Bold)
94          Button("terminateSelfWithResult").fontSize(20).onClick(() => {
95            this.session?.terminateSelfWithResult({
96              resultCode: 1,
97              want: {
98                bundleName: "com.example.embeddeddemo",
99                abilityName: "ExampleEmbeddedAbility",
100              }});
101          })
102        }.width('100%').height('100%')
103      }
104    }
105    ```
106
1075. 在工程Module对应的[module.json5配置文件](../quick-start/module-configuration-file.md)中注册EmbeddedUIExtensionAbility，type标签需要设置为“embeddedUI”，srcEntry标签表示当前EmbeddedUIExtensionAbility组件所对应的代码路径。
108
109    ```json
110    {
111      "module": {
112        "extensionAbilities": [
113          {
114            "name": "EmbeddedUIExtAbility",
115            "icon": "$media:icon",
116            "description": "EmbeddedUIExtAbility",
117            "type": "embeddedUI",
118            "srcEntry": "./ets/EmbeddedUIExtAbility/EmbeddedUIExtAbility.ets"
119          },
120        ]
121      }
122    }
123    ```
124
125
126
127## 开发EmbeddedUIExtensionAbility使用方
128
129开发者可以在[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。
130- ohos.extension.processMode.hostSpecified控制非首次启动的EmbeddedUIExtensionAbility是否运行在同[UIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)的进程中，参数是进程名称。例如，"ohos.extension.processMode.hostSpecified"： "com.ohos.inentexecutedemo:share"。
131- ohos.extension.processMode.hostInstance控制启动的EmbeddedUIExtensionAbility是否按照独立进程启动，传入false时，按照UIExtensionAbility的进程模型启动，入参true的时候，不管被拉起的UIExtensionAbility配置的是什么进程模型，都会新增一个进程，例如，"ohos.extension.processMode.hostInstance": "true"。
132
133ohos.extension.processMode.hostSpecified和ohos.extension.processMode.hostInstance同时配置时，hostSpecified优先，会运行在指定的进程中。
134如在首页文件：pages/Index.ets中添加如下内容：
135```ts
136import { Want } from '@kit.AbilityKit';
137import { BusinessError } from '@kit.BasicServicesKit';
138
139@Entry
140@Component
141struct Index {
142  @State message: string = 'Message: '
143  private want: Want = {
144    bundleName: "com.example.embeddeddemo",
145    abilityName: "EmbeddedUIExtAbility",
146    parameters: {
147      'ohos.extension.processMode.hostInstance': 'true'
148    }
149  }
150
151  build() {
152    Row() {
153      Column() {
154        Text(this.message).fontSize(30)
155        EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
156          .width('100%')
157          .height('90%')
158          .onTerminated((info: TerminationInfo) => {
159            this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
160          })
161          .onError((error: BusinessError) => {
162            this.message = 'Error: code = ' + error.code;
163          })
164      }
165      .width('100%')
166    }
167    .height('100%')
168  }
169}
170```
171