HarmonyOS NEXT鸿蒙开发：自定义组件（struct、build()函数）

作者：马育民 • • 阅读：10074

介绍

在ArkUI中，UI显示的内容均为 组件，分两类：

  • 由框架直接提供的称为 系统组件
  • 由 开发者 定义的称为 自定义组件

在进行 UI 界面开发时，通常不是简单的将系统组件进行组合使用，而是需要考虑代码可复用性、业务逻辑与UI分离，后续版本演进等因素。
所以，在开发中，需要创建自定义组件

特点

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

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

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

自定义组件的结构

例子

@Entry
@Component
struct MyComponent {
  build() {
  }
}

struct

使用 ArkTS (Ability Kit TypeScript) 语言时，struct 用于构建 声明式UI，用于封装 UI 结构、状态和行为。所有的页面和可复用组件都需要通过 struct 来定义，是构建界面的基础。

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

注意命名：自定义组件名、类名、函数名不能和系统组件名相同。

build()函数

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

@Component

详见链接：
https://www.malaoshi.top/show_1GW1y74VVbrb.html

规则（重要）

所有声明在 build() 函数的语句，我们统称为 UI描述，要遵循以下规则：

  • @Entry 装饰的自定义组件，build() 函数下的 根节点唯一且必要，且 必须为容器组件

    @Entry
@Component
struct MyComponent {
build() {
  // @Entry修饰的，根节点唯一且必要，必须为容器组件
  Row() {
    ChildComponent() 
  }
}
}

  • 没有 @Entry 装饰的自定义组件，其 build() 函数下的根节点唯一且必要，可以 不是 容器组件。ForEach 禁止作为根节点。

    @Component
struct ChildComponent {
build() {
  // 根节点唯一且必要，可为非容器组件
  Image('test.jpg')
}
}

  • 不允许声明本地变量，反例如下

    build() {
// 反例：不允许声明本地变量
let a: number = 1;
}

  • 不允许在UI描述里直接使用 console.info ，但允许在方法或者函数里使用，反例如下。

    build() {
// 反例：不允许console.info
console.info('print debug log');
}

  • 不允许创建本地的作用域，反例如下

    build() {
// 反例：不允许本地作用域
{
  ...
}
}

  • 不允许调用没有用 @Builder 装饰的方法，允许系统组件的参数是TS方法的返回值。

    @Component
struct ParentComponent {
doSomeCalculations() {
}

calcTextValue(): string {
  return 'Hello World';
}

@Builder doSomeRender() {
  Text(`Hello World`)
}

build() {
  Column() {
    // 反例：不能调用没有用@Builder装饰的方法
    this.doSomeCalculations();
    // 正例：可以调用
    this.doSomeRender();
    // 正例：参数可以为调用TS方法的返回值
    Text(this.calcTextValue())
  }
}
}

  • 不允许使用 switch 语法，如果需要使用条件判断，请使用if。示例如下。

    build() {
Column() {
  // 反例：不允许使用switch语法
  switch (expression) {
    case 1:
      Text('...')
      break;
    case 2:
      Image('...')
      break;
    default:
      Text('...')
      break;
  }
  // 正例：使用if
  if(expression == 1) {
    Text('...')
  } else if(expression == 2) {
    Image('...')
  } else {
    Text('...')
  }
}
}

  • 不允许使用表达式，反例如下。

    build() {
Column() {
  // 反例：不允许使用表达式
  (this.aVar > 10) ? Text('...') : Image('...')
}
}

  • 不允许直接改变状态变量，反例如下。详细分析见 @State 常见问题：不允许在build里改状态变量

    @Component
struct CompA {
@State col1: Color = Color.Yellow;
@State col2: Color = Color.Green;
@State count: number = 1;
build() {
  Column() {
    // 应避免直接在Text组件内改变count的值
    Text(`${this.count++}`)
      .width(50)
      .height(50)
      .fontColor(this.col1)
      .onClick(() => {
        this.col2 = Color.Red;
      })
    Button("change col1").onClick(() =>{
      this.col1 = Color.Pink;
    })
  }
  .backgroundColor(this.col2)
}
}

@Entry

详见链接：
https://www.malaoshi.top/show_1GW1y5nDSf7y.html

EntryOptions

命名路由跳转选项。

  • routeName：类型：string，表示作为命名路由页面的名字。
  • storage：类型：LocalStorage，页面级的UI状态存储。

成员函数

自定义组件除了必须要实现 build() 函数外，还可以实现自定义 成员函数，特点：

  • 自定义组件的成员函数为 私有的，且 不建议 声明成 静态函数。

成员变量

自定义组件可以包含 成员变量，成员变量具有以下约束：

自定义组件的成员变量为 私有的，且 不建议 声明成 静态变量。

原文出处：/show_1GW1QfElTpD.html

吉ICP备15003043号