harmony 鸿蒙IsolatedComponent (System API)

2025-06-12
浏览 (3)

IsolatedComponent (System API)

IsolatedComponent is designed to support the embedding and display of UIs provided by independent .abc files within the current page, with the displayed content running in a restricted worker thread.

The FolderStack component is usually used in modular development scenarios where .abc file hot update is required.

NOTE

This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.

The APIs provided by this module are system APIs.

Constraints

Specifications Constraints

This component does not support preview.
.abc files must pass the VerifyAbc verification to be used in this component.
Construction parameter updates are not supported; only the initial input is effective.
Nesting of IsolatedComponent components is not supported.

Experience Constraints

When an IsolatedComponent component is created, there is a certain amount of time required for the restricted worker thread to load and render the .abc file layout. During this period, the background color of the IsolatedComponent is displayed.
The main thread and the restricted worker thread handle layout rendering asynchronously, which can lead to desynchronization in page changes caused by layout alterations or rotations.
Event transmission between the main thread and the restricted worker thread is managed asynchronously, and there is no support for event bubbling between threads. As a result, UI interactions between threads may encounter event conflicts.

Security Constraints

Displaying an independent .abc file through the IsolatedComponent component in the host process means that the .abc file content is fully accessible to the host, granting the host the control over the file content. For security-sensitive situations where such open access could be a risk, the use of this feature is disabled.
Running independent .abc files in a restricted worker thread offers a level of security, as the .abc file content is isolated and does not interfere with the main thread.

Child Components

Not supported

APIs

IsolatedComponent(options: IsolatedOptions)

Creates an IsolatedComponent component to display the .abc file executed in a restricted worker thread.

Parameters

Name	Type	Mandatory	Description
options	IsolatedOptions	Yes	Construction parameters.

IsolatedOptions

Describes the optional construction parameters during IsolatedComponent construction.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	.abc file information to load.
worker	RestrictedWorker	Yes	Restricted worker thread where the .abc file is running.

Attributes

Only the width, height, and backgroundColor universal attributes are supported.

Events

The universal events are not supported.

Events are asynchronously passed to the restricted worker thread after coordinate conversion.

The following events are supported:

onError

onError(callback:ErrorCallback)

Invoked when an error occurs during the running of the IsolatedComponent. You can obtain the error information based on the code, name, and message parameters in the callback and rectify the exception accordingly.

Parameters

Name	Type	Description
callback	ErrorCallback	Error information.

Example: Loading an IsolatedComponent

This example demonstrates the basic usage of the IsolatedComponent component. The sample application’s bundleName is “com.example.isolateddemo”, and the component uses the .abc file and an extension page from the same application as the embedded content. The specific testing steps after building the application project are as follows: 1. Build the HAP in DevEco Studio and install it on the device. 2. Upload the generated modules.abc file to the application sandbox path** /data/app/el2/100/base/com.example.isolateddemo/haps/entry/files** using DevEco Studio or the hdc tool. 3. Open the application page and click the verifyAbc button to verify the .abc file, which logs “VerifyAbc successfully.” 4. Click the showIsolatedComponent button to display the IsolatedComponent with the content “Hello World.”

Restricted Worker thread script ets/workers/OhCardWorker.ets: “`ts // OhCardWorker.ets import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from ‘@kit.ArkTS’; const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {} workerPort.onmessageerror = (e: MessageEvents) => {} workerPort.onerror = (e: ErrorEvent) => {}


- Home page (**ets/pages/Index.ets**) loaded by the entry ability (**EntryAbility**):
  ```ts
  import { worker } from '@kit.ArkTS';
  import { bundleManager } from '@kit.AbilityKit';
  import { BusinessError } from '@kit.BasicServicesKit';

  // Verify the .abc file and copy it to the specified sandbox path.
  function VerifyAbc(abcPaths: Array<string>, deleteOriginalFiles: boolean) {
    try {
      bundleManager.verifyAbc(abcPaths, deleteOriginalFiles, (err) => {
        if (err) {
          console.error("VerifyAbc failed, error message: " + err.message);
        } else {
          console.info("VerifyAbc successfully.");
        }
      });
    } catch (err) {
      let message = (err as BusinessError).message;
      console.error("VerifyAbc failed, error message: " + message);
    }
  }

  @Entry
  @Component
  struct Index {
    @State isShow: boolean = false;
    @State resourcePath: string = "";
    @State abcPath: string = "";
    @State entryPoint: string = "";
    // .abc file name
    private fileName: string = "modules";
    // Bundle name of the application to which the .abc file belongs
    private bundleName: string = "com.example.isolateddemo";
    // Restricted Worker thread
    private worker ?: worker.RestrictedWorker = new worker.RestrictedWorker("entry/ets/workers/OhCardWorker.ets");

    build() {
      Row() {
        Column() {
          // 1. Verify the .abc file.
          Button("verifyAbc").onClick(() => {
            let abcFilePath = `${getContext(this).filesDir}/${this.fileName}.abc`;
            console.log("abcFilePath: " + abcFilePath);
            VerifyAbc([abcFilePath], false);
          }).height(100).width(100)

          // 2. Display the IsolatedComponent.
          Button("showIsolatedComponent").onClick(() => {
            if (!this.isShow) {
              // Resource path
              this.resourcePath = `${getContext(this).filesDir}/${this.fileName}.hap`;
              // Sandbox path after the .abc file is verified
              this.abcPath = `/abcs${getContext(this).filesDir}/${this.fileName}`;
              // Entry to the page to be displayed
              this.entryPoint = `${this.bundleName}/entry/ets/pages/extension`;
              this.isShow = true;
            }
          }).height(100).width(100)

          if (this.isShow) {
            IsolatedComponent({
              want: {
                "parameters": {
                  "resourcePath": this.resourcePath,
                  "abcPath": this.abcPath,
                  "entryPoint": this.entryPoint
                }
              },
              worker: this.worker
            })
              .width(300)
              .height(300)
              .onError((err) => {
                console.info("onError : " + JSON.stringify(err));
              })
          }
        }
        .width('100%')
      }
      .height('100%')
    }
  }

The entry page file ets/pages/extension.ets, which runs in a restricted Worker thread, needs to be configured in the resources/base/profile/main_pages.json file with the following content:

@Entry
@Component
struct Extension {
@State message: string = 'Hello World';


build() {
  RelativeContainer() {
    Text(this.message)
      .id('HelloWorld')
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
      .alignRules({
        center: { anchor: '__container__', align: VerticalAlign.Center },
        middle: { anchor: '__container__', align: HorizontalAlign.Center }
      })
  }
  .height('100%')
  .width('100%')
}
}

Add the requestPermissions tag in the module.json5 configuration file to allow the execution of dynamically distributed Ark bytecode in restricted mode:

"requestPermissions": [
{
  "name": "ohos.permission.RUN_DYN_CODE",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "inuse"
  }
}
]