鸿蒙Next创建自定义组件总结

一、引言

在鸿蒙Next开发中，自定义组件是构建高效、可维护UI的重要组成部分。它具有可组合、可重用以及数据驱动UI更新等特点，能帮助开发者更好地实现代码复用、业务逻辑与UI分离等目标。本文将详细总结创建自定义组件的相关知识，包括其基本结构、成员函数/变量、参数规定、build()函数以及通用样式等方面。

二、自定义组件基本结构

基于struct实现
- 自定义组件由struct + 自定义组件名 + {...}构成，不能有继承关系，struct实例化可省略new。且自定义组件名不能和系统组件名相同。
@Component装饰器
- 仅能装饰struct关键字声明的数据结构，被装饰后具备组件化能力，需实现build方法描述UI，一个struct只能被一个@Component装饰。从API version 11开始，@Component可接受一个可选的bool类型参数freezeWhenInactive用于控制组件冻结。
build()函数
- 用于定义自定义组件的声明式UI描述，是自定义组件必须定义的函数。
@Entry装饰器
- 装饰的自定义组件将作为UI页面的入口，单个UI页面最多只能有一个@Entry装饰的自定义组件。从API version 10开始，@Entry可接受可选的LocalStorage参数或EntryOptions参数。
@Reusable装饰器（API version 10开始支持在ArkTS卡片中使用）
- 使自定义组件具备可复用能力。

三、成员函数/变量

成员函数
- 为私有，不建议声明为静态函数。
成员变量
- 为私有，不建议声明为静态变量。成员变量本地初始化要求因情况而异，具体参考状态管理。部分情况下可从父组件通过参数传递初始化。

四、自定义组件参数规定

初始化参数

在build方法里创建自定义组件时，根据装饰器规则初始化参数。例如：

 @Component
 struct MyComponent {
   private countDownFrom: number = 0;
   private color: Color = Color.Blue;
   build() {
   }
 }
 @Entry
 @Component
 struct ParentComponent {
   private someColor: Color = Color.Pink;
   build() {
     Column() {
       // 创建MyComponent实例并初始化参数
       MyComponent({ countDownFrom: 10, color: this.someColor })
     }
   }
 }

传递函数作为参数

父组件可将函数传递给子组件，子组件可调用该函数，如：

 @Entry
 @Component
 struct Parent {
   @State cnt: number = 0
   submit: () => void = () => {
     this.cnt++;
   }
   build() {
     Column() {
       Text(`${this.cnt}`)
       Son({ submitArrow: this.submit })
     }
   }
 }
 @Component
 struct Son {
   submitArrow?: () => void
   build() {
     Row() {
       Button('add')
        .width(80)
        .onClick(() => {
           if (this.submitArrow) {
             this.submitArrow()
           }
         })
     }
    .justifyContent(FlexAlign.SpaceBetween)
    .height(56)
   }
 }

五、build()函数规则

根节点要求
- @Entry装饰的自定义组件，build()函数下根节点唯一且必须为容器组件（ForEach禁止作为根节点）。
- @Component装饰的自定义组件，build()函数下根节点唯一且可为非容器组件（ForEach禁止作为根节点）。
其他限制
- 不允许声明本地变量。
- 不允许在UI描述里直接使用console.info（方法或函数里可用）。
- 不允许创建本地作用域。
- 不允许调用没有用@Builder装饰的方法，但系统组件参数可为TS方法返回值。
- 不允许使用switch语法，需用if进行条件判断。
- 不允许使用表达式。
- 不允许直接改变状态变量（会造成循环渲染风险，不同版本更新方式有差异且可能影响性能）。

六、自定义组件通用样式

通过“.”链式调用的形式设置通用样式，但给自定义组件设置样式时，实际上是给组件套了一个不可见容器组件，样式设置在该容器组件上而非直接在组件自身。例如：

@Component
struct MyComponent2 {
  build() {
    Button(`Hello World`)
  }
}
@Entry
@Component
struct MyComponent {
  build() {
    Row() {
      MyComponent2()
       .width(200)
       .height(300)
       .backgroundColor(Color.Red)
    }
  }
}

掌握鸿蒙Next中创建自定义组件的这些知识，开发者能够更加灵活、高效地构建应用UI，提升应用的质量和可维护性。