鸿蒙开发：了解@Builder装饰器

原创

程序员一鸣

发布于 2025-02-15 09:21:42

11900

代码可运行

文章被收录于专栏：HarmonyOS点石成金HarmonyOS点石成金

运行总次数：0

代码可运行

前言

本文代码案例基于Api13，温馨提示：内容相对来说比较简单，如果您已掌握，略过即可。

如果说一个页面中组件有很多，我们都统一写到build函数中，显而易见，会导致build函数代码非常冗余，并且在有相同UI时，也做不到可复用效果，那么，针对这一问题如何解决呢？答案就是抽取出来；在页面内实现UI组件的抽取剥离，其实，在实际的开发中是非常常见的，也就是通过@Builder装饰器来实现。

简单案例

以下是一个多文本展示案例，非常简单，就是几个Text组件，未抽取之前，都统一写在build函数之中。

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text("文本测试一")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Text("文本测试二")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Text("文本测试三")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Text("文本测试四")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
    .height('100%')
    .width('100%')
  }
}

使用@Builder装饰器之后：

@Entry
@Component
struct Index {
  @Builder
  textView(text: string) {
    Text(text)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      this.textView("文本测试一")
      this.textView("文本测试二")
      this.textView("文本测试三")
      this.textView("文本测试四")
    }
    .height('100%')
    .width('100%')
  }
}

显而可见，代码相比未抽取之前，简洁了很多，虽然上述只是一个案例，然而在实际的开发中，页面的复杂程度远远比案例复杂，所以更应该合理的使用@Builder装饰器。

什么是@Builder？

在前言中已经明确告知，@Builder它是一个装饰器，主要用于UI元素的复用以及抽取，@Builder所修饰的函数，统称为“自定义构建函数”，可以在函数中定义任何的UI组件，用法和build中的使用是一样的。

使用方式

@Builder装饰器有两种使用方式，一种是定义在UI组件内，也就是上述的使用方式，可以称为私有自定义构建函数，也就是只能给当前的UI组件进行使用，别的UI组件是无法使用的。

与私有自定义构建函数相对应的就是全局自定义构建函数，它可以实现任意的UI组件进行使用，需要用到function关键字，如果定义在非UI组件中，需要用export关键字导出。

我们可以自定义一个扩展类，把共用的组件定义在这里。

@Builder
export function TextView(text: string) {
  Text(text)
    .fontSize(20)
    .fontWeight(FontWeight.Bold)
}

任何一个页面或者UI组件中都可以使用。

import { TextView } from './BuilderView'

@Entry
@Component
struct Index {
  build() {
    Column() {
      TextView("文本测试一")
      TextView("文本测试二")
      TextView("文本测试三")
      TextView("文本测试四")
    }
    .height('100%')
    .width('100%')
  }
}

当然了，如果不是全局共用，仅仅是本页面内共用，也可以使用这种方式来实现。

数据更新

当我们直接更改传递的变量时，会发现@Builder修饰的函数内并没有实现数据改变，如下案例，怎么点击Button都不会发生改变。

@Entry
@Component
struct Index {
  @State testContent: string = "文本测试"

  @Builder
  textView(text: string) {
    Text(text)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      this.textView(this.testContent)
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这是因为，在@Builder修饰的函数内部，不允许改变参数值，也就是状态变量的改变不会引起@Builder方法内的UI刷新，那么要怎么实现可以动态改变@Builder修饰的函数里的数据呢，有两种方式，一种是，直接把当前的引用也就是当前的类传递过去，直接调用，另一种则是使用引用传递。

this指向当前类

把以上的代码做下更改，由传递值，直接传递当前的类，也就是当前的this，由this直接调用。

@Entry
@Component
struct Index {
  @State testContent: string = "文本测试"

  @Builder
  textView(_this: Index) {
    Text(_this.testContent)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      this.textView(this)
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

可以发现点击Button后，数据实现了动态改变。

按引用传递参数

直接传递当前的this，可以说是最简单的方式，除了这种方式之外，我们还可是使用引用传递参数的方式，动态改变数据，也就是通过传递对象的方式。

class TestBean {
  testContent?: string;
}

@Entry
@Component
struct Index {
  @State testContent: string = "文本测试"

  @Builder
  textView(testBean: TestBean) {
    Text(testBean.testContent)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      this.textView({ testContent: this.testContent })
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

可以看到，以上的数据传递，也能实现数据的动态改变，相对于this传递，使用这种方式则更加灵活，毕竟在实际的开发中，我们可能会遇到多个页面共用组件的情况，传递this显然只适合当前的页面，如果多个页面复用，还是以对象形式传递为佳。

由此可见，在使用@Builder进行参数传递的时候，如果要引起@Builder方法内的UI刷新，可以按照引用传递参数进行实现，按值传递是无法更新UI的。

参数规则

@Builder修饰的函数，其定义的参数类型，必须和传递的类型保持一致，并且不允许undefined、null和返回undefined、null的表达式。

还有一点非常重要，@Builder如果传入的参数是两个或两个以上，不会触发动态渲染UI，比如，上面的案例中，我们随便增加一个参数。

 @Builder
  textView(testBean: TestBean, isBoolean: boolean) {
    Text(testBean.testContent)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }

运行后可以发现，数据是无法动态更改的，如果有多个值如何传递呢？两种方式，第一种以this为传递对象，使用this调用更多定义的参数，第二种就是直接定义在对象里，既然都以对象的形式进行传递了，何不都直接定义在对象里呢？

@ComponentV2装饰器更新

使用ComponentV2装饰器，遵循的道理一样，也就是使用简单数据类型不可以触发UI的刷新。

@Entry
@ComponentV2
struct Index {
  @Local testContent: string = "文本测试"

  @Builder
  textView(testContent: string) {
    Column() {
      Text(testContent)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
  }

  build() {
    Column() {
      this.textView(this.testContent)
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

如果要更新UI的话，还是需要按引用传递参数，也就是修改为对象传递。

class TestBean {
  testContent?: string;
}

@Entry
@ComponentV2
struct Index {
  @Local testContent: string = "文本测试"

  @Builder
  textView(testBean: TestBean) {
    Column() {
      Text(testBean.testContent)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
  }

  build() {
    Column() {
      this.textView({ testContent: this.testContent })
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

如果直接以对象的形式传递，不借助成员变量，需要使用@ObservedV2修饰的对象类和@Trace修饰属性才可以触发UI的刷新。

@ObservedV2
class TestBean {
 @Trace testContent: string = "文本测试";
}

@Entry
@ComponentV2
struct Index {
  @Local testBean: TestBean = new TestBean()

  @Builder
  textView(testBean: TestBean) {
    Column() {
      Text(testBean.testContent)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
    }
  }

  build() {
    Column() {
      this.textView(this.testBean)
      Button("改变")
        .margin({ top: 10 })
        .onClick(() => {
          this.testBean.testContent = "文本测试2"
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}