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

一、引言

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

二、自定义组件基本结构

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

三、成员函数/变量

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

四、自定义组件参数规定

1. 初始化参数
   • 在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 })}}
     }
     

2. 传递函数作为参数
   • 父组件可将函数传递给子组件，子组件可调用该函数，如：

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

五、build()函数规则

1. 根节点要求
   • @Entry装饰的自定义组件，build()函数下根节点唯一且必须为容器组件（ForEach禁止作为根节点）。
   • @Component装饰的自定义组件，build()函数下根节点唯一且可为非容器组件（ForEach禁止作为根节点）。
2. 其他限制
   • 不允许声明本地变量。
   • 不允许在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，提升应用的质量和可维护性。