鸿蒙_引用自定义构建函数@BuilderParam在自定义组件中的使用

梁山好汉（Ls_man）2026-04-08 11:21

在ArkUI的学习中，通过@BuilderParam修饰的参数就是引用自定义构建函数，它可以接受一个自定义构建函数。当我们编写了一个自定义组件后，想要在使用时替换其中的某一部分UI内容，就可以在组件内部可以将这部分抽离放到自定义构建函数内，我们来验证一下如何使用：

TypeScript 复制代码

@Entry
@Component
struct TestBuilderParamInComponent {
  @State message: string = 'Test @BuilderParam In Component';

  //编写一个自定义构建函数，用于替换自定义组件的部分UI
  @Builder
  builderInMainPage() {
    Row() {
      Text('2、').fontColor(Color.Green)
      Text('将自定义构建函数作为参数传入组件')
    }
  }

  build() {
    Column() {
      Text(this.message)
        .margin({ bottom: 10 })
        .fontSize(18)
        .fontWeight(FontWeight.Bold)

      //不传参（如果自定义组件内的builderParamInComp加了@Require不传会报错）
      CompWithOneBuilderParam()

      //普通传参
      CompWithOneBuilderParam({
        builderParamInComp: this.builderInMainPage
      })

      //尾随闭包（在自定义组件后的大括号内直接写UI组件）
      CompWithOneBuilderParam() {
        Row() {
          Text('3、').fontColor(Color.Red)
          Text('通过尾随闭包方式直接传入组件')
        }
      }

    }
    .padding(10)
    .height('100%')
    .width('100%')
  }
}

//自定义组件
@Component
struct CompWithOneBuilderParam {
  //自定义构建函数
  @Builder
  builderInComp() {
    Text('1、自定义构建函数的默认内容')
  }

  //引用自定义构建函数（把自定义构建函数整体作为一个参数）
  //@Require
  @BuilderParam
  builderParamInComp: () => void = this.builderInComp;

  build() {
    Column({ space: 10 }) {
      Text('这是一个自定义组件').fontWeight(FontWeight.Bold)
      this.builderParamInComp()
    }
    .padding(10)
    .width('100%')
    .margin({ bottom: 10 })
    .border({ width: 1, color: Color.Blue })
  }
}

通过测试我们发现，如果自定义组件内部只包含一个引用自定义构建函数（@BuilderParam修饰的参数）时，还可以通过尾随闭包的方式使用，当有多个引用自定义构建函数时，只能通过普通传参方式使用。如果某个参数被@Require修饰了，那么该参数就是必传项，如果不写就会在编辑器内标红。

运行效果如下：