DynamicComponent (系统接口)

DynamicComponent用于支持在本页面内嵌入显示独立Abc（.abc文件）提供的UI，展示的内容在Worker线程中运行。

通常用于动态加载Abc页面的模块化开发场景。

说明：

• 本模块为系统接口。
• 本模块接口仅可在Stage模型下使用。

起始版本： 26.0.0

子组件

无

接口

DynamicComponent(options: DynamicOptions)

创建DynamicComponent组件，用于显示Worker线程中运行的Abc UI。

起始版本： 26.0.0

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	DynamicOptions	是	DynamicComponent的构造配置参数，用于配置要加载的Abc页面入口、运行Worker及显示选项。

Worker

type Worker = Worker

用于运行Abc的Worker线程对象。

起始版本： 26.0.0

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

类型	说明
Worker	用于在独立线程中运行Abc。

ErrorCallback

type ErrorCallback = ErrorCallback

错误回调类型，用于接收异常信息。

起始版本： 26.0.0

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

类型	说明
ErrorCallback	用于接收运行过程中的异常信息。

DynamicOptions

用于在DynamicComponent构造时传递参数。

起始版本： 26.0.0

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

名称	类型	只读	可选	说明
entryPoint	string	否	否	要加载的abc页面入口。
worker	Worker	否	否	运行Abc的Worker。
backgroundTransparent	boolean	否	是	是否启用组件背景透明。 true：启用背景透明；false：不启用背景透明。 默认值：false
allowCrossProcessNesting	boolean	否	是	是否允许跨进程UIExtensionComponent嵌套。 true：允许跨进程嵌套；false：不允许跨进程嵌套。 默认值：false

属性

支持通用属性。

事件

支持以下事件：

onError

onError(callback: ErrorCallback)

DynamicComponent运行过程中发生异常时触发该回调。使用callback异步回调。

起始版本： 26.0.0

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	ErrorCallback	是	回调函数，入参用于接收异常信息。

示例

示例1（加载独立Abc页面并监听运行异常）

本示例展示了DynamicComponent的基本用法，通过配置DynamicOptions加载指定Worker线程中运行的Abc页面，并通过onError回调处理运行异常。

从API版本26.0.0开始，新增onError事件。

import { worker } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  @State errorMessage: string = '';
  private worker?: worker.ThreadWorker = new worker.ThreadWorker(
    "entry/ets/workers/Worker.ets", { name: "dc-worker" }
  )

  build() {
    Column() {
      Text('DynamicComponent示例').fontSize(20).margin(10)

      if (this.errorMessage) {
        Text('错误信息: ' + this.errorMessage).fontSize(14).fontColor(Color.Red).margin(10)
      }

      DynamicComponent({
        entryPoint: 'com.example.myapplication/entry/ets/pages/DynamicPage',
        worker: this.worker,
        backgroundTransparent: false,
        allowCrossProcessNesting: false
      })
        .width('100%')
        .height('60%')
        .onError((error: BusinessError) => {
          this.errorMessage = `code: ${error.code}, message: ${error.message}`;
          hilog.error(0x0000, 'DynamicComponentDemo', 'onError: ' + this.errorMessage);
        })
        .borderWidth(10)
        .borderColor(Color.Red)
    }
    .height('100%')
    .width('100%')
  }
}

• 以下为用于运行Abc的Worker线程对象的实现文件/src/main/ets/workers/Worker.ets。

  import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';
  
  const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
  
  workerPort.onmessage = (event: MessageEvents) => {
  };
  
  workerPort.onmessageerror = (event: MessageEvents) => {
  };
  
  workerPort.onerror = (event: ErrorEvent) => {
  };
  

• 嵌入显示的Abc页面/src/main/ets/pages/DynamicPage.ets。

  @Entry
  @Component
  struct DynamicPage {
    build() {
      Column() {
        Text('this is ability in DC')
          .fontSize(20)
          .margin(10)
      }
      .height('100%')
      .width('100%')
      .borderWidth(10)
      .borderColor(Color.Blue)
      .align(Alignment.Top)
    }
  }
  

• 为提供方页面配置路由main_pages.json。

  {
    "src": [
      "pages/Index",
      "pages/DynamicPage"
    ]
  }