关于openharmony:OpenHarmony自定义构建函数Builder装饰器

后面章节介绍了如何创立一个自定义组件。该自定义组件外部 UI 构造固定，仅与应用方进行数据传递。ArkUI 还提供了一种更轻量的 UI 元素复用机制 @Builder，@Builder 所装璜的函数遵循 build()函数语法规定，开发者能够将重复使用的 UI 元素形象成一个办法，在 build 办法里调用。

为了简化语言，咱们将 @Builder 装璜的函数也称为“自定义构建函数”。

阐明：

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

装璜器应用阐明

自定义组件内自定义构建函数
定义的语法：
@Builder MyBuilderFunction() { ...}

应用办法：
this.MyBuilderFunction() { ...}

● 容许在自定义组件内定义一个或多个自定义构建函数，该函数被认为是该组件的公有、非凡类型的成员函数。

● 自定义构建函数能够在所属组件的 build 办法和其余自定义构建函数中调用，但不容许在组件外调用。

● 在自定义函数体中，this 指代以后所属组件，组件的状态变量能够在自定义构建函数内拜访。倡议通过 this 拜访自定义组件的状态变量而不是参数传递。

全局自定义构建函数
定义的语法：

@Builder function MyGlobalBuilderFunction() { ...}

应用办法：
MyGlobalBuilderFunction()

● 全局的自定义构建函数能够被整个利用获取，不容许应用 this 和 bind 办法。

● 如果不波及组件状态变动，倡议应用全局的自定义构建办法。

参数传递规定[

自定义构建函数的参数传递有按值传递和按援用传递两种，均需恪守以下规定：

● 参数的类型必须与参数申明的类型统一，不容许 undefined、null 和返回 undefined、null 的表达式。

● 在 @Builder 润饰的函数外部，不容许扭转参数值。

● @Builder 内 UI 语法遵循 UI 语法规定。

按援用传递参数
按援用传递参数时，传递的参数可为状态变量，且状态变量的扭转会引起 @Builder 办法内的 UI 刷新。ArkUI 提供 $$ 作为按援用传递参数的范式。

class ABuilderParam {paramA1: string = ''paramB1: string =''}

@Builder function ABuilder($$ : ABuilderParam) {...}
class ABuilderParam {paramA1: string = ''}

@Builder function ABuilder($$: ABuilderParam) {Row() {Text(`UseStateVarByReference: ${$$.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {Column() {
      // Pass the this.label reference to the ABuilder component when the ABuilder component is called in the Parent component.
      ABuilder({paramA1: this.label})
      Button('Click me').onClick(() => {
        // After Click me is clicked, the UI text changes from Hello to ArkUI.
        this.label = 'ArkUI';
      })
    }
  }
}

按值传递参数
调用 @Builder 装璜的函数默认按值传递。当传递的参数为状态变量时，状态变量的扭转不会引起 @Builder 办法内的 UI 刷新。所以当应用状态变量的时候，举荐应用按援用传递。

@Builder function ABuilder(paramA1: string) {Row() {Text(`UseStateVarByValue: ${paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  label: string = 'Hello';
  build() {Column() {ABuilder(this.label)
    }
  }
}