harmony 鸿蒙EmbeddedUIExtensionAbility

2025-06-06
浏览 (2)

EmbeddedUIExtensionAbility

Overview

EmbeddedUIExtensionAbility is an ExtensionAbility component of the EMBEDDED_UI type. It provides the capability of embedded UIs across processes.

The EmbeddedUIExtensionAbility must be used together with the EmbeddedComponent. Specifically, with the EmbeddedComponent, you can embed the UI provided by the EmbeddedUIExtensionAbility into a UIAbility of the same application. The EmbeddedUIExtensionAbility runs in a process independent of the UIAbility for UI layout and rendering. It is usually used in modular development scenarios where process isolation is required.

NOTE

Currently, the EmbeddedUIExtensionAbility and EmbeddedComponent are supported only on devices configured with multiple processes.

The EmbeddedComponent can be used only in the UIAbility, and the EmbeddedUIExtensionAbility to start must belong to the same application as the UIAbility.

The EmbeddedUIExtensionAbility supports the multiton pattern and inherits the process model of the UIExtensionAbility. For details about the multiton pattern and process configuration of the UIExtensionAbility, see UIExtensionAbility.

The EmbeddedUIExtensionAbility provides related capabilities through the UIExtensionContext and UIExtensionContentSession. In this document, the started EmbeddedUIExtensionAbility is called the provider, and the EmbeddedComponent that starts the EmbeddedUIExtensionAbility is called the client.

Developing the EmbeddedUIExtensionAbility Provider

Lifecycle

The EmbeddedUIExtensionAbility class provides the lifecycle callbacks onCreate, onSessionCreate, onSessionDestroy, onForeground, onBackground, and onDestroy. You must override them as required.

onCreate: called to initialize the service logic when an EmbeddedUIExtensionAbility is created.
onSessionCreate: called when a UIExtensionContentSession instance is created for the EmbeddedUIExtensionAbility.
onSessionDestroy: called when a UIExtensionContentSession instance is destroyed for the EmbeddedUIExtensionAbility.
onForeground: called when the EmbeddedUIExtensionAbility is switched from the background to the foreground.
onBackground: called when the EmbeddedUIExtensionAbility is switched from the foreground to the background.
onDestroy: called to clear resources when the EmbeddedUIExtensionAbility is destroyed.

How to Develop

To implement a provider, create an EmbeddedUIExtensionAbility in DevEco Studio as follows:

In the ets directory of a module in the project, right-click and choose New > Directory to create a directory named EmbeddedUIExtAbility.
Right-click the EmbeddedUIExtAbility directory, and choose New > File to create a file named EmbeddedUIExtAbility.ets.

Open the EmbeddedUIExtAbility.ets file and import its dependencies. Customize a class that inherits from EmbeddedUIExtensionAbility and implement the lifecycle callbacks onCreate, onSessionCreate, onSessionDestroy, onForeground, onBackground, and onDestroy.

import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';


const TAG: string = '[ExampleEmbeddedAbility]';


export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility {
  onCreate() {
    console.log(TAG, `onCreate`);
  }


  onForeground() {
    console.log(TAG, `onForeground`);
  }


  onBackground() {
    console.log(TAG, `onBackground`);
  }


  onDestroy() {
    console.log(TAG, `onDestroy`);
  }


  onSessionCreate(want: Want, session: UIExtensionContentSession) {
    console.log(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`);
    let param: Record<string, UIExtensionContentSession> = {
      'session': session
    };
    let storage: LocalStorage = new LocalStorage(param);
    session.loadContent('pages/extension', storage);
  }


  onSessionDestroy(session: UIExtensionContentSession) {
    console.log(TAG, `onSessionDestroy`);
  }
}

Write the entry page file pages/Index.ets, which will be loaded in onSessionCreate of the EmbeddedUIExtensionAbility.

import { UIExtensionContentSession } from '@kit.AbilityKit';


@Entry()
@Component
struct Extension {
  @State message: string = 'EmbeddedUIExtensionAbility Index';
  localStorage: LocalStorage|undefined = this.getUIContext().getSharedLocalStorage();
  private session: UIExtensionContentSession|undefined = this.localStorage?.get<UIExtensionContentSession>('session');


  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Button('terminateSelfWithResult').fontSize(20).onClick(() => {
        this.session?.terminateSelfWithResult({
          resultCode: 1,
          want: {
            bundleName: 'com.example.embeddeddemo',
            abilityName: 'ExampleEmbeddedAbility'
          }});
      })
    }.width('100%').height('100%')
  }
}

Register the EmbeddedUIExtensionAbility in the module.json5 file of the module in the project. Set type to embeddedUI and srcEntry to the code path of the EmbeddedUIExtensionAbility.

{
  "module": {
    "extensionAbilities": [
      {
        "name": "EmbeddedUIExtAbility",
        "icon": "$media:icon",
        "description": "EmbeddedUIExtAbility",
        "type": "embeddedUI",
        "srcEntry": "./ets/EmbeddedUIExtAbility/EmbeddedUIExtAbility.ets"
      },
    ]
  }
}

Developing the EmbeddedUIExtensionAbility Client

You can load the EmbeddedUIExtensionAbility in the application through the EmbeddedComponent on the UIAbility page. Two fields are added to want.parameters for the EmbeddedUIExtensionAbility: ohos.extension.processMode.hostSpecified and ohos.extension.processMode.hostInstance. - ohos.extension.processMode.hostSpecified specifies the name of the process in which the EmbeddedUIExtensionAbility that is not started for the first time runs. If this field is not configured, the EmbeddedUIExtensionAbility runs in the same process as the UIExtensionAbility. Example configuration: “ohos.extension.processMode.hostSpecified”: “com.ohos.inentexecutedemo:share.” - ohos.extension.processMode.hostInstance specifies whether to start the EmbeddedUIExtensionAbility as an independent process. If false is passed in, the EmbeddedUIExtensionAbility is started based on the UIExtensionAbility process model. If true is passed in, a process is created, regardless of the process model configured for the UIExtensionAbility. Example configuration: “ohos.extension.processMode.hostInstance”: “true”.

If both fields are configured, ohos.extension.processMode.hostSpecified takes precedence, meaning that the EmbeddedUIExtensionAbility runs in the specified process. For example, add the following content to the home page file pages/Index.ets:

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State message: string = 'Message: '
  private want: Want = {
    bundleName: 'com.example.embeddeddemo',
    abilityName: 'EmbeddedUIExtAbility',
    parameters: {
      'ohos.extension.processMode.hostInstance': 'true'
    }
  }

  build() {
    Row() {
      Column() {
        Text(this.message).fontSize(30)
        EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
          .width('100%')
          .height('90%')
          .onTerminated((info: TerminationInfo) => {
            this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
          })
          .onError((error: BusinessError) => {
            this.message = 'Error: code = ' + error.code;
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}