HarmonyOS Learning Road Ark Development Framework - Learning ArkTS Language (Basic Grammar 4)

@BuilderParam decorator: references @Builder functions

When you create a custom component and want to add specific functions to the component, such as adding a click jump operation in the custom component. If you directly embed the event method in the component, this function will be added in all places where the custom component is introduced. To solve this problem, ArkUI introduces the @BuilderParam decorator. @BuilderParam is used to decorate variables pointing to @Builder methods. Developers can assign values ​​to this property when initializing custom components to add specific functions to custom components. This decorator is used to declare an element described by any UI, similar to a slot placeholder.

Decorator Instructions

Initialize the method decorated with @BuilderParam

Methods decorated with @BuildParam can only be initialized by custom build functions (methods decorated with @Builder).

• Initialize @BuilderParam locally using the custom build function of the owning custom component or the global custom build function.

@Builder function GlobalBuilder0() {}

@Component
struct Child {
  @Builder doNothingBuilder() {};

  @BuilderParam aBuilder0: () => void = this.doNothingBuilder;
  @BuilderParam aBuilder1: () => void = GlobalBuilder0;
  build(){}
}

• A method decorated with @BuildParam to initialize the child component with a custom build function of the parent component.

@Component
struct Child {
  @BuilderParam aBuilder0: () => void;

  build() {
    Column() {
      this.aBuilder0()
    }
  }
}

@Entry
@Component
struct Parent {
  @Builder componentBuilder() {
    Text(`Parent builder `)
  }

  build() {
    Column() {
      Child({ aBuilder0: this.componentBuilder })
    }
  }
}

• Note that this points to the correct one.

In the following example, when the Parent component calls this.componentBuilder(), this.label points to the component it belongs to, namely "Parent". @Builder componentBuilder() is passed to the child component @BuilderParam aBuilder0. When this.aBuilder0() is called in the Child component, this.label points to the label of the Child, namely "Child".

@Component
struct Child {
  label: string = `Child`
  @BuilderParam aBuilder0: () => void;

  build() {
    Column() {
      this.aBuilder0()
    }
  }
}

@Entry
@Component
struct Parent {
  label: string = `Parent`

  @Builder componentBuilder() {
    Text(`${this.label}`)
  }

  build() {
    Column() {
      this.componentBuilder()
      Child({ aBuilder0: this.componentBuilder })
    }
  }
}

scenes to be used

Parameter initialization component

The method decorated with @BuilderParam can be in two forms with or without parameters, and must match the type of @Builder method pointed to. The method type decorated by @BuilderParam needs to be consistent with the @Builder method type.

@Builder function GlobalBuilder1($$ : {label: string }) {
  Text($$.label)
    .width(400)
    .height(50)
    .backgroundColor(Color.Blue)
}

@Component
struct Child {
  label: string = 'Child'
  // 无参数类，指向的componentBuilder也是无参数类型
  @BuilderParam aBuilder0: () => void;
  // 有参数类型，指向的GlobalBuilder1也是有参数类型的方法
  @BuilderParam aBuilder1: ($$ : { label : string}) => void;

  build() {
    Column() {
      this.aBuilder0()
      this.aBuilder1({label: 'global Builder label' } )
    }
  }
}

@Entry
@Component
struct Parent {
  label: string = 'Parent'

  @Builder componentBuilder() {
    Text(`${this.label}`)
  }

  build() {
    Column() {
      this.componentBuilder()
      Child({ aBuilder0: this.componentBuilder, aBuilder1: GlobalBuilder1 })
    }
  }
}

trailing closure initialization component

When using properties decorated with @BuilderParam in custom components, they can also be initialized through trailing closures. When initializing a custom component, the component is followed by a curly brace "{}" to form a trailing closure scenario.

illustrate

In this scenario, there is one and only one attribute decorated with @BuilderParam in the custom component.

Pass the contents of the trailing closure as a @Builder decorated function to @BuilderParam. Examples are as follows:

// xxx.ets
@Component
struct CustomContainer {
  @Prop header: string;
  @BuilderParam closer: () => void

  build() {
    Column() {
      Text(this.header)
        .fontSize(30)
      this.closer()
    }
  }
}

@Builder function specificParam(label1: string, label2: string) {
  Column() {
    Text(label1)
      .fontSize(30)
    Text(label2)
      .fontSize(30)
  }
}

@Entry
@Component
struct CustomContainerUser {
  @State text: string = 'header';

  build() {
    Column() {
      // 创建CustomContainer，在创建CustomContainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
      // 作为传递给子组件CustomContainer @BuilderParam closer: () => void的参数
      CustomContainer({ header: this.text }) {
        Column() {
          specificParam('testA', 'testB')
        }.backgroundColor(Color.Yellow)
        .onClick(() => {
          this.text = 'changeHeader';
        })
      }
    }
  }
}