OpenHarmony自定义组件介绍

一、创建自定义组件

在ArkUI中，UI显示的内容均为组件，由框架直接提供的称为系统组件，由开发者定义的称为自定义组件。在进行 UI 界面开发时，通常不是简单的将系统组件进行组合使用，而是需要考虑代码可复用性、业务逻辑与UI分离，后续版本演进等因素。因此，将UI和部分业务逻辑封装成自定义组件是不可或缺的能力。

自定义组件具有以下特点：

● 可组合：允许开发者组合使用系统组件、及其属性和方法。

● 可重用：自定义组件可以被其他组件重用，并作为不同的实例在不同的父组件或容器中使用。

● 数据驱动UI更新：通过状态变量的改变，来驱动UI的刷新。

以下示例展示了自定义组件的基本用法。

@Component
struct HelloComponent {
  @State message: string = 'Hello, World!';
 
  build() {
    // HelloComponent自定义组件组合系统组件Row和Text
    Row() {
      Text(this.message)
        .onClick(() => {
          // 状态变量message的改变驱动UI刷新，UI从'Hello, World!'刷新为'Hello, ArkUI!'
          this.message = 'Hello, ArkUI!';
        })
    }
  }
}

HelloComponent可以在其他自定义组件中的build()函数中多次创建，实现自定义组件的重用。

class HelloComponentParam {
  message: string = ""
}
 
@Entry
@Component
struct ParentComponent {
  param: HelloComponentParam = {
    message: 'Hello, World!'
  }
 
  build() {
    Column() {
      Text('ArkUI message')
      HelloComponent(param);
      Divider()
      HelloComponent(param);
    }
  }
}

要完全理解上面的示例，需要了解自定义组件的以下概念定义，本文将在后面的小节中介绍：

●  自定义组件的基本结构

●  成员函数/变量

●  自定义组件的参数规定

●  build()函数

●  自定义组件通用样式

自定义组件的基本结构

● struct：自定义组件基于struct实现，struct + 自定义组件名 + {…}的组合构成自定义组件，不能有继承关系。对于struct的实例化，可以省略new。

说明：自定义组件名、类名、函数名不能和系统组件名相同。

● @Component：@Component装饰器仅能装饰struct关键字声明的数据结构。struct被@Component装饰后具备组件化的能力，需要实现build方法描述UI，一个struct只能被一个@Component装饰。

说明：从API version 9开始，该装饰器支持在ArkTS卡片中使用。

@Component
struct MyComponent {
}

● build()函数：build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。

@Component
struct MyComponent {
  build() {
  }
}

● @Entry：@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，最多可以使用@Entry装饰一个自定义组件。@Entry可以接受一个可选的 LocalStorage 的参数。

说明：

从API version 9开始，该装饰器支持在ArkTS卡片中使用。

从API version 10开始，@Entry可以接受一个可选的 LocalStorage 的参数或者一个可选的 EntryOptions 参数。

@Entry
@Component
struct MyComponent {
}

EntryOptions10+命名路由跳转选项。

名称	类型	必填	说明
routeName	string	否	表示作为命名路由页面的名字。
storage	LocalStorage	否	页面级的UI状态存储。

@Entry({ routeName : 'myPage' })
@Component
struct MyComponent {
}

<