HarmonyOS NEXT - @Builder自定义构建函数

ArkUI提供了一种轻量的UI元素复用机制@Builder，该自定义组件内部UI结构固定，仅与使用方进行数据传递，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。

可以理解为：一种可重复使用的组件集

装饰器使用说明
@Builder装饰器有两种使用方式，分别是定义在自定义组件内部的私有自定义构建函数和定义在全局的全局自定义构建函数。

定义：

@Builder MyBuilderFunction() {
   }

        

          
        
        
        

          

          AI 代码解读
        
      
      

使用：

this.MyBuilderFunction()

        

          
        
        
        

          

          AI 代码解读
        
      
      

私有自定义构建函数

@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() {
   
      // 无参数
      this.showTextBuilder()
      // 有参数
      this.showTextValueBuilder('Hello @Builder')
    }
  }
}

        

          
        
        
        

          

          AI 代码解读
        
      
      

• 允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。
• 私有自定义构建函数允许在自定义组件内、build方法和其他自定义构建函数中调用。
• 在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。

全局自定义构建函数

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

        

          
        
        
        

          

          AI 代码解读
        
      
      

• 如果不涉及组件状态变化，建议使用全局的自定义构建方法。
• 全局自定义构建函数允许在build方法和其他自定义构建函数中调用。

代码实例：BuilderPage

@Entry
@Component
struct BuilderPage {
   
  @State message: string = '第2节 @Builder自定义构建函数';

  @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%')
  }
}

        

          
        
        
        

          

          AI 代码解读
        
      
      

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

• 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。
• 在@Builder修饰的函数内部，不允许改变参数值。
• @Builder内UI语法遵循UI语法规则。
• 只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。