鸿蒙开发：熟知@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 {@BuilderitemLayout(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: () => voidbuild() {Column() {if (this.layout != undefined) {this.layout()}if (this.layout2 != undefined) {this.layout2()}}}
}

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

@Entry
@Component
struct Index {testContent: string = "Index"@BuildertestView() {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: () => voidbuild() {Column() {if (this.layout != undefined) {this.layout()}}}
}

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

@Entry
@Component
struct Index {@State testContent: string = "测试数据一"@BuildertextView() {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: () => voidbuild() {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%')}
}