关于openharmony: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+ 命名路由跳转选项。

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

● @Reusable：@Reusable 装璜的自定义组件具备可复用能力

阐明：从 API version 10 开始，该装璜器反对在 ArkTS 卡片中应用。

@Reusable
@Component
struct MyComponent {
}

成员函数 / 变量
自定义组件除了必须要实现 build()函数外，还能够实现其余成员函数，成员函数具备以下束缚：
● 不反对动态函数。
● 成员函数的拜访始终是公有的。

自定义组件能够蕴含成员变量，成员变量具备以下束缚：
● 不反对动态成员变量。
● 所有成员变量都是公有的，变量的拜访规定与成员函数的拜访规定雷同。
● 自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否须要本地初始化，是否须要从父组件通过参数传递初始化子组件的成员变量，请参考状态治理。

自定义组件的参数规定
从上文的示例中，咱们曾经理解到，能够在 build 办法或者 @Builder 装璜的函数里创立自定义组件，在创立的过程中，参数能够被提供给组件。

@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
      MyComponent({countDownFrom: 10, color: this.someColor})
    }
  }
}

build()函数
所有申明在 build()函数的语言，咱们统称为 UI 描述语言，UI 描述语言须要遵循以下规定：
● @Entry 装璜的自定义组件，其 build()函数下的根节点惟一且必要，且必须为容器组件，其中 ForEach 禁止作为根节点。@Component 装璜的自定义组件，其 build()函数下的根节点惟一且必要，能够为非容器组件，其中 ForEach 禁止作为根节点。

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

@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;
    }
  }
}

● 不容许应用表达式，反例如下。

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

自定义组件通用款式

自定义组件通过“.”链式调用的模式设置通用款式。

@Component
struct MyComponent2 {build() {Button(`Hello World`)
  }
}

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

阐明：ArkUI 给自定义组件设置款式时，相当于给 MyComponent2 套了一个不可见的容器组件，而这些款式是设置在容器组件上的，而非间接设置给 MyComponent2 的 Button 组件。通过渲染后果咱们能够很分明的看到，背景色彩红色并没有间接失效在 Button 上，而是失效在 Button 所处的开发者不可见的容器组件上。

二、页面和自定义组件生命周期

在开始之前，咱们先明确自定义组件和页面的关系：
● 自定义组件：@Component 装璜的 UI 单元，能够组合多个零碎组件实现 UI 的复用。
● 页面：即利用的 UI 页面。能够由一个或者多个自定义组件组成，@Entry 装璜的自定义组件为页面的入口组件，即页面的根节点，一个页面有且仅能有一个 @Entry。只有被 @Entry 装璜的组件才能够调用页面的生命周期。

页面生命周期，即被 @Entry 装璜的组件生命周期，提供以下生命周期接口：
● onPageShow：页面每次显示时触发。
● onPageHide：页面每次暗藏时触发一次。
● onBackPress：当用户点击返回按钮时触发。

组件生命周期，即个别用 @Component 装璜的自定义组件的生命周期，提供以下生命周期接口：
● aboutToAppear：组件行将呈现时回调该接口，具体机会为在创立自定义组件的新实例后，在执行其 build()函数之前执行。
● aboutToDisappear：在自定义组件行将析构销毁时执行。

生命周期流程如下图所示，下图展现的是被 @Entry 装璜的组件（首页）生命周期。

依据下面的流程图，咱们从自定义组件的初始创立、从新渲染和删除来具体解释。

自定义组件的创立和渲染流程
1.  自定义组件的创立：自定义组件的实例由 ArkUI 框架创立。
2.  初始化自定义组件的成员变量：通过本地默认值或者构造方法传递参数来初始化自定义组件的成员变量，初始化程序为成员变量的定义程序。
3.  如果开发者定义了 aboutToAppear，则执行 aboutToAppear 办法。
4.  在首次渲染的时候，执行 build 办法渲染零碎组件，如果有自定义子组件，则创立自定义组件的实例。在执行 build() 函数的过程中，框架会察看每个状态变量的读取状态，将保留两个 map：
a.  状态变量 -> UI 组件（包含 ForEach 和 if）。
b.  UI 组件 -> 此组件的更新函数，即一个 lambda 办法，作为 build()函数的子集，创立对应的 UI 组件并执行其属性办法，示意如下。

build() {
  ...
  this.observeComponentCreation(() => {Button.create();
  })

  this.observeComponentCreation(() => {Text.create();
  })
  ...
}

当利用在后盾启动时，此时利用过程并没有销毁，所以仅须要执行 onPageShow。

自定义组件从新渲染
当事件句柄被触发（比方设置了点击事件，即触发点击事件）扭转了状态变量时，或者 LocalStorage / AppStorage 中的属性更改，并导致绑定的状态变量更改其值时：
1.  框架察看到了变动，将启动从新渲染。
2.  依据框架持有的两个 map（自定义组件的创立和渲染流程中第 4 步），框架能够晓得该状态变量治理了哪些 UI 组件，以及这些 UI 组件对应的更新函数。执行这些 UI 组件的更新函数，实现最小化更新。

自定义组件的删除
如果 if 组件的分支扭转，或者 ForEach 循环渲染中数组的个数扭转，组件将被删除：

1.  在删除组件之前，将调用其 aboutToDisappear 生命周期函数，标记着该节点将要被销毁。ArkUI 的节点删除机制是：后端节点间接从组件树上摘下，后端节点被销毁，对前端节点解援用，以后端节点曾经没有援用时，将被 JS 虚拟机垃圾回收。

2.  自定义组件和它的变量将被删除，如果其有同步的变量，比方 @Link、@Prop、@StorageLink，将从同步源上勾销注册。

不倡议在生命周期 aboutToDisappear 内应用 async await，如果在生命周期的 aboutToDisappear 应用异步操作（Promise 或者回调办法），自定义组件将被保留在 Promise 的闭包中，直到回调办法被执行完，这个行为阻止了自定义组件的垃圾回收。以下示例展现了生命周期的调用机会：

// Index.ets
import router from '@ohos.router';

@Entry
@Component
struct MyComponent {
  @State showChild: boolean = true;

  // 只有被 @Entry 装璜的组件才能够调用页面的生命周期
  onPageShow() {console.info('Index onPageShow');
  }
  // 只有被 @Entry 装璜的组件才能够调用页面的生命周期
  onPageHide() {console.info('Index onPageHide');
  }

  // 只有被 @Entry 装璜的组件才能够调用页面的生命周期
  onBackPress() {console.info('Index onBackPress');
  }

  // 组件生命周期
  aboutToAppear() {console.info('MyComponent aboutToAppear');
  }

  // 组件生命周期
  aboutToDisappear() {console.info('MyComponent aboutToDisappear');
  }

  build() {Column() {
      // this.showChild 为 true，创立 Child 子组件，执行 Child aboutToAppear
      if (this.showChild) {Child()
      }
      // this.showChild 为 false，删除 Child 子组件，执行 Child aboutToDisappear
      Button('delete Child').onClick(() => {this.showChild = false;})
      // push 到 Page2 页面，执行 onPageHide
      Button('push to next page')
        .onClick(() => {router.pushUrl({ url: 'pages/Page2'});
        })
    }

  }
}

@Component
struct Child {
  @State title: string = 'Hello World';
  // 组件生命周期
  aboutToDisappear() {console.info('[lifeCycle] Child aboutToDisappear')
  }
  // 组件生命周期
  aboutToAppear() {console.info('[lifeCycle] Child aboutToAppear')
  }

  build() {Text(this.title).fontSize(50).onClick(() => {this.title = 'Hello ArkUI';})
  }
}

以上示例中，Index 页面蕴含两个自定义组件，一个是被 @Entry 装璜的 MyComponent，也是页面的入口组件，即页面的根节点；一个是 Child，是 MyComponent 的子组件。只有 @Entry 装璜的节点才能够失效页面的生命周期办法，所以 MyComponent 中申明了以后 Index 页面的页面生命周期函数。MyComponent 和其子组件 Child 也同时申明了组件的生命周期函数。

●利用冷启动的初始化流程为：MyComponent aboutToAppear –> MyComponent build –> Child aboutToAppear –> Child build –> Child build 执行结束 –> MyComponent build 执行结束 –> Index onPageShow。
●点击“delete Child”，if 绑定的 this.showChild 变成 false，删除 Child 组件，会执行 Child aboutToDisappear 办法。
●点击“push to next page”，调用 router.pushUrl 接口，跳转到另外一个页面，以后 Index 页面暗藏，执行页面生命周期 Index onPageHide。此处调用的是 router.pushUrl 接口，Index 页面被暗藏，并没有销毁，所以只调用 onPageHide。跳转到新页面后，执行初始化新页面的生命周期的流程。
●如果调用的是 router.replaceUrl，则以后 Index 页面被销毁，执行的生命周期流程将变为：Index onPageHide –> MyComponent aboutToDisappear –> Child aboutToDisappear。上文曾经提到，组件的销毁是从组件树上间接摘下子树，所以先调用父组件的 aboutToDisappear，再调用子组件的 aboutToDisappear，而后执行初始化新页面的生命周期流程。
●点击返回按钮，触发页面生命周期 Index onBackPress，且触发返回一个页面后会导致以后 Index 页面被销毁。
●最小化利用或者利用进入后盾，触发 Index onPageHide。以后 Index 页面没有被销毁，所以并不会执行组件的 aboutToDisappear。利用回到前台，执行 Index onPageShow。
●退出利用，执行 Index onPageHide –> MyComponent aboutToDisappear –> Child aboutToDisappear。