HarmonyOS 鸿蒙Next 【应用开发-ArkTS】@Builder函数和@BuilderParam装饰器妙用与应用

ArkTS的高级语法范式

使用 @Builder 自定义构建函数

1. 构建函数内部的 this 指向

@Entry
@Component
struct ExampleComponent {
  @State buttonText: string = 'Click me';

  [@Builder](/user/Builder)
  BuildButton() {
    Button(this.buttonText)
      .onClick(() => {
        console.log(`Button Clicked! Current text: ${this.buttonText}`);
      });
  }

  build() {
    Column() {
      Text('Welcome to ArkTS!')
        .fontSize(20)
      // 调用自定义构建函数
      this.BuildButton()
    }
  }
}

2. 构建函数的参数传递

[@Builder](/user/Builder) MyBuilderFunction(param: string) {
  // 构建函数体
}

通过参数传递，你可以将外部数据灵活地传递给自定义构建函数，实现更加通用和可配置的构建逻辑。

3. 全局自定义构建函数

[@Builder](/user/Builder)
function GlobalBuilderFunction() {
  // 全局构建函数体
}

在应用的任何地方都可以调用全局构建函数，实现全局范围内的构建逻辑复用。

最佳实践与建议

1. 合理使用参数传递：在使用@Builder 装饰器时，根据实际需求选择合适的参数传递方式。按值传递适用于不需要响应外部变化的场景，而按引用传递适用于需要响应外部变化的场景。
2. 充分利用 this 指向：在自定义构建函数内部，充分利用this 指向，访问和操作组件内的状态变量，实现更灵活的构建逻辑。
3. 构建函数的命名规范： 为了提高代码的可读性，建议根据构建函数的功能给予清晰的命名，使其用途一目了然。

@BuilderParam装饰器：引用@Builder函数

初始化@BuilderParam装饰的方法

[@Builder](/user/Builder) function GlobalBuilder0() {}

@Component
struct Child {
  [@Builder](/user/Builder) doNothingBuilder() {};

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

用父组件自定义构建函数初始化子组件@BuilderParam装饰的方法

@Component
struct Child {
  [@BuilderParam](/user/BuilderParam) aBuilder0: () => void;

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

@Entry
@Component
struct Parent {
  [@Builder](/user/Builder) componentBuilder() {
    Text(`Parent builder `)
  }

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

使用场景

参数初始化组件

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

@Component
struct Child {
  [@BuilderParam](/user/BuilderParam) aBuilder0: () => void;
  [@BuilderParam](/user/BuilderParam) aBuilder1: ($$ : { label : string}) => void;

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

@Entry
@Component
struct Parent {
  [@Builder](/user/Builder) componentBuilder() {
    Text(`${this.label}`)
  }

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

尾随闭包初始化组件

@Component
struct CustomContainer {
  @Prop header: string;
  [@BuilderParam](/user/BuilderParam) closer: () => void

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

[@Builder](/user/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](/user/BuilderParam) closer: () => void的参数
      CustomContainer({ header: this.text }) {
        Column() {
          specificParam('testA', 'testB')
        }.backgroundColor(Color.Yellow)
        .onClick(() => {
          this.text = 'changeHeader';
        })
      }
    }
  }
}

通过不同的初始化方式和使用场景，开发者可以更好地掌握 @BuilderParam 装饰器的使用方法，提高代码的可读性和可维护性。

结语

通过深入理解@Builder 装饰器，我们可以更好地使用自定义构建函数来实现UI元素的复用，提高代码的可维护性和可读性。这一特性使得ArkTS在应用开发中更加灵活，让开发者能够更轻松地构建复杂的用户界面。在实际应用中，合理使用@Builder装饰器将为项目带来更多的便利。