鸿蒙【Harmony】@Builder 自定义构建函数

若自定义的组件内部UI结构固定，且仅与使用方进行数据传递。则无需单独写一个自定义组件文件，可直接在使用方内进行定义。

即UI元素复用机制@Builder，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。

定义一个自定义构建函数：

@Builder myBuilderComponent(){
    // todo    
}

 

在使用方内使用：

this.myBuilderComponent()

 

全局自定义构建函数

定义,即多加function

@Builder function  myGlobalBuilderComponent(){
  Text('这是全局自定义构建函数')
    .fontSize(20)
    .fontColor(Color.Red)
}

 

使用

 myGlobalBuilderComponent()

 

注意：全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。

 

规则：

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

一、按引用传递参数

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

如下示例，传递参数 message给自定义构建函数，使用按引用传递方式，当点击button改变message值的时候，会导致@Builder方法内的UI刷新

// 参数传递规则示例
@Entry
@Component
struct ParmsTest {
  @State message: string = 'Hello World'

  build() {
    Row() {
      Column(){
　　　　　// 使用自定义构建函数，传入值message
        myComponentView({showContent: this.message})
        
        Button('点击修改内容')
          .fontSize(30)
          .type(ButtonType.Capsule)
          .onClick(()=>{
            this.message = '内容变化'
          })
      }
    }
    .height('100%')
  }
}
// 定义一个全局自定义构建函数
// 使用按引用传值方式
@Builder function myComponentView($$: { showContent: string }){
  Row(){
    Text($$.showContent)
      .fontSize(20)
      .fontColor(Color.Red)
  }
}

 

二、按值传递参数

调用@Builder装饰的函数默认按值传递。当传递的参数为状态变量时，状态变量的改变不会引起@Builder方法内的UI刷新。所以当使用状态变量的时候，推荐使用按引用传递。

如下示例，传递参数 message给自定义构建函数，使用按值传递方式，当点击button改变message值的时候，并不会导致@Builder方法内的UI刷新

// 参数传递规则示例
@Entry
@Component
struct ParmsTest {
  @State message: string = 'Hello World'

  build() {
    Row() {
      Column(){
        otherComponent(this.message,'按值传递参数')
        Button('点击修改内容')
          .fontSize(30)
          .type(ButtonType.Capsule)
          .onClick(()=>{
            this.message = '内容变化'
          })
      }
    }
    .height('100%')
  }
}

// 定义一个全局自定义构建构建函数
// 使用按值传递参数方式
@Builder function otherComponent(showContent:string,typeContent:string){
  Column(){
    Text(showContent)
      .fontSize(30)
      .fontColor(Color.Blue)
    Text('传递方式:'+typeContent)
    .fontSize(30)
      .fontColor(Color.Blue)
  }
}