How to use HarmonyOS NEXT - @Builder Custom Build Function?

note:Before reading this document, it is recommended to read: Basic Grammar Overview, Declarative UI Description, Custom Components - Create Custom Components.

ArkUI provides a lightweight UI element reuse mechanism @builder, which has a fixed internal UI structure and only transfers data with the user. Developers can abstract reused UI elements into a method and call it in the build method.

It can be understood as a reusable set of components

Decorator usage instructions
There are two ways to use the @builder decorator, which are private custom build functions defined within custom components and global custom build functions defined globally.

definition:

@Builder MyBuilderFunction() {}

use

this.MyBuilderFunction()

Private custom build function

@Entry
@Component
struct BuilderDemo {
  @Builder
  showTextBuilder() {
    Text('Hello World')
      .fontSize(30)
      .fontWeight(FontWeight.Bold)
  }
  @Builder
  showTextValueBuilder(param: string) {
    Text(param)
      .fontSize(30)
      .fontWeight(FontWeight.Bold)
  }
  build() {
    Column() {
      // No parameters
      this.showTextBuilder()
      // There are parameters
      this.showTextValueBuilder('Hello @Builder')
    }
  }
}

·Allow the definition of one or more @ Builder methods within a custom component, which are considered private, special type member functions of the component.
·Private user-defined building functions can be called in user-defined components, build methods and other user-defined building functions.
·In a custom function body, 'this' refers to the current component to which it belongs, and the component's state variables can be accessed within the custom build function. Suggest accessing the state variables of custom components through this instead of passing parameters.

Global custom build function

@Builder
function showTextBuilder() {
  Text('Hello World. This is builded by @Builder')
    .fontSize(30)
    .fontWeight(FontWeight.Bold)
}
@Entry
@Component
struct BuilderDemo {
  build() {
    Column() {
      showTextBuilder()
    }
  }
}

·If there are no component state changes involved, it is recommended to use a global custom build method.
·Global user-defined building functions can be called in the build method and other user-defined building functions.

Code Example: BuilderPage

@Entry
@Component
struct BuilderPage {
  @State message: string = '@Builder custom build function';

  @Builder
  task(taskName:string,state:boolean){
    Row(){
      Text(taskName)
      Blank()
      Text(state?'已完成':'未完成').fontColor(state?Color.Green:Color.Red)
    }.width('100%').padding(10).borderWidth({bottom:1})
  }

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      Text('任务清单')
        .width('100%')
        .backgroundColor('#EEEEEE')
        .fontWeight(FontWeight.Bold)
        .textAlign(TextAlign.Center)
        .padding(10)
        .borderWidth({bottom:1})

      Row(){
        Text('晨跑')
        Blank()
        Text('已完成').fontColor(Color.Green)
      }.width('100%').padding(10).borderWidth({bottom:1})

      Row(){
        Text('早读')
        Blank()
        Text('未完成').fontColor(Color.Red)
      }.width('100%').padding(10).borderWidth({bottom:1})


      this.task('默写',true)
      this.task('练习书法',false)
    }
    .height('100%')
    .width('100%')
  }
}

parameter passing rule
There are two types of parameter passing for custom build functions: value passing and reference passing, both of which must follow the following rules:
·The type of the parameter must be consistent with the declared type of the parameter, and expressions that return undefined or null are not allowed.
·Within functions decorated with @ Builder, it is not allowed to change parameter values.
·The UI syntax in @ Builder follows the rules of UI syntax.
·Only when a parameter is passed in, and the parameter needs to be passed directly to the object literal, will it be passed by reference. All other passing methods are passed by value.