HarmonyOS NEXT鸿蒙开发：创建自定义组件-马育民老师

# 介绍

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

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

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

### 特点

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

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

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

# 自定义组件的结构

## 例子

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

## struct

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

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

## @Component：

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

`@Component` 可以接受一个可选的bool类型参数。

## build()函数

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

### 规则（重要）

所有声明在 `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

`@Entry` 装饰的自定义组件将作为UI页面的 **入口**。在单个UI页面中，最多可以使用 `@Entry` **装饰 一个自定义组件**

#### 参数

`@Entry` 可以接受一个可选的 `LocalStorage` 的参数或者一个可选的 `EntryOptions` 参数。

#### 例子

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

## EntryOptions

命名路由跳转选项。

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

# 成员函数

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

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

# 成员变量

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

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

原文出处：http://malaoshi.top/show_1GW1QfElTpD.html