鸿蒙开发：熟知@BuilderParam装饰器

前言

本文代码案例基于Api13。

在实际的开发中，我们经常会遇到自定义组件的情况，比如通用的列表组件，选项卡组件等等，由于使用方的样式不一，子组件是动态变化的，针对这一情况，就不得不让使用方把子组件视图传递过来，如何来接收这个UI视图，这就是@BuilderParam装饰器的作用。

简单案例

简单封装一个通用的List组件，由于每个列表的数据和UI布局都是不一样的，那么这两块就需要暴露给使用方，代码如下：

/**
 * AUTHOR:AbnerMing
 * DATE:2025/2/13
 * INTRODUCE:通用的列表组件
 * */
@Component
export struct ListView {
  dataList?: Object[] //数据源
  @BuilderParam itemLayout: (item: Object, index: number) => void //子视图

  build() {
    List() {
      ForEach(this.dataList, (item: Object, index: number) => {
        ListItem() {
          this.itemLayout(item, index)
        }
      })
    }
  }
}

以上的自定义List组件，我们就可以用在任何页面，只需要传递数据和子视图即可。

@Entry
@Component
struct Index {
  
  @Builder
  itemLayout(item: Object, index: number) {
    Text(item.toString())
  }

  build() {
    Column() {
      ListView({
        dataList: [0, 1, 2, 3, 4, 5, 6],
        itemLayout: this.itemLayout
      })
    }
    .height('100%')
    .width('100%')
  }
}

@BuilderParam装饰器让UI组件赋予了动态的变化，可以根据自身需要实现不同的效果，避免了实例增加了相同的功能，从而实现更高程度的组件复用和代码解耦。

使用方式

@BuilderParam装饰器，常见于自定义组件，暴露给使用方进行调用，用来承接@Builder装饰器修饰的函数，使用方式很简单，格式如下：

@BuilderParam test: () => void

如果接收参数，直接在括号中添加即可。

除了正常的由调用者传递UI组件之外，我们也可以初始化一个默认的视图，直接在后面等于即可，这样在未传递的话就会加载默认的视图。

@Builder
testView() {
    
}

@BuilderParam test: () => void = this.testView()

this指向问题

如下所示，我们自定义了一个组件，定义了两个@BuilderParam，用于接收传递的UI视图：

@Component
export struct TestView {
  testContent: string = "TestView"
  @BuilderParam layout: () => void
  @BuilderParam layout2: () => void

  build() {
    Column() {
      if (this.layout != undefined) {
        this.layout()
      }
      if (this.layout2 != undefined) {
        this.layout2()
      }
    }

  }
}

我们通过三种方式，分别调用@Builder修饰的函数。

@Entry
@Component
struct Index {
  testContent: string = "Index"

  @Builder
  testView() {
    Text(`${this.testContent}`)
      .fontSize(20)
      .margin({ top: 20 })
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      this.testView()
      TestView({ layout: this.testView })
      TestView({
        layout2: () => {
          this.testView()
        }
      })
    }
    .height('100%')
    .width('100%')
  }
}

运行之后，效果如下：

我们可以看到，直接调用@Builder修饰的函数，也就是this.testView()这行代码，this指向的是当前的Index类，其值也是取的Index中值。

当我们以参数的形式，传递给@BuilderParam时，也就是TestView({ layout: this.testView })这行代码，可以发现，其this并不是指的是Index类，而是自定义组件TestView，取的是TestView中所定义的值。

当我们针对自定义组件，换种方式使用时，也就是如下方式使用：

TestView({
        layout2: () => {
          this.testView()
        }
      })

可以发现，this又切换为了当前类Index，这是因为箭头函数的this指向的是宿主对象，所以其值取的是Index类中的。

所以在有@BuilderParam传递UI视图时，一定要注意this的指向问题，这也是为什么很多同学遇到在@Builder修饰的函数中为什么不刷新数据的问题，其原因就是this指向不对。

数据更新

更新@BuilderParam装饰器，本意就是更新对应的@Builder修饰的函数，这个在《鸿蒙开发：了解@Builder装饰器》一篇中已经重点做了讲解，这里再重新概述一下。

简单自定义一个组件，使用 @BuilderParam装饰器，对外暴露一个UI视图。

@Component
export struct TestView {
  @BuilderParam layout: () => void

  build() {
    Column() {
      if (this.layout != undefined) {
        this.layout()
      }
    }
  }
}

上面已经讲述过this指向问题了，如果数据在本页面内，那么一定要使用箭头函数来调用@Builder修饰的函数，才能实现数据的更新。

@Entry
@Component
struct Index {
  @State testContent: string = "测试数据一"

  @Builder
  textView() {
    Text(this.testContent)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      TestView({
        layout: () => {
          this.textView()
        }
      })
      Button("点击")
        .onClick(() => {
          this.testContent = "测试数据二"
        })
    }
    .height('100%')
    .width('100%')
  }
}

相关总结

在声明@BuilderParam的时候，如果未有默认值，那么在不传递的情况下，会发生异常崩溃，为了解决这一问题，有两种方案，方案一，主动设置默认值：

@Builder
testView() {
    
}

@BuilderParam test: () => void = this.testView()

方案二，在调用的地方进行非空校验：

@BuilderParam test: () => void

  build() {
    if (this.test != undefined) {
      this.test()
    }
  }

@BuilderParam用于接收@Builder定义的函数，私有和全局都可以。

定义全局的@Builder。

@Builder
export function TextView() {
  Text("测试数据一")
    .fontSize(20)
    .fontWeight(FontWeight.Bold)
}

调用

@Entry
@Component
struct Index {
  build() {
    Column() {
      TestView({ layout: TextView })
    }
    .height('100%')
    .width('100%')
  }
}