鸿蒙入门——ArkUI 自定义组件通过自定义构建函数@Builder系和@BuilderParam高效复用UI（七）

CrazyMo_

已于 2025-03-21 17:52:55 修改

阅读量1.9k

点赞数 34

CC 4.0 BY-SA版权

文章标签： ArkUI TypeScript ArkTS 鸿蒙系统 HarmonyOS

于 2025-01-18 12:00:00 首次发布

本文链接：https://blog.csdn.net/CrazyMo_/article/details/143242145

文章大纲

引言
一、@Builder 装饰器
二、@BuilderParam 装饰器（指向@Builder方法的变量的修饰器）

引言

自定义组件的目的就是为了复用，除了传统的封装、组合现有的系统View控件之外，还支持另一种更高效的复用机制，即通过@Builder进行封装，接下来就介绍下@Builder系。

ArkTS 是基于TypeScript 的基础进行的扩展，其中各种类似@Builder的UI装饰器就是扩展出来的。

一、@Builder 装饰器

1、@Builder 装饰器概述

@Builder是ArkUI提供的一种更轻量的UI元素复用机制，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法并在build方法里调用。而被@Builder 装饰的函数则成为自定义构建函数，同属来说就是把一些需要重复使用的UI的声明及初始化封装到一个函数中，再把这个函数使用@Buidder修饰，那么这个函数就成为了一个自定义构建函数，你在build方法中就可以直接调用完成UI构建。

2、@Builder 装饰器基本语法

2.1、声明自定义组件内的自定义构建函数

就是在自定义组件内定义一个函数，然后使用@Builder修饰，在其函数体内就像是在build方法里定义UI语法一样，这样子就可以在build中重复调用这个函数

@Builder YourMethodName() { ... }

2.2、自定义组件使用自定义构建函数

在自定义组件内的build通过调用方式使用自己的自定义构建函数

可以思考一哈？那么其他组件可以使用外部组件的自定义构建函数么？

this.YourMethodName()

允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。
自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。

3、全局自定义构建函数

在自定义组件内定义一个函数，然后使用@Builder修饰就是自定义构建函数，而全局自定义构建函数则是在函数名面前增加一个关键字 function 再使用@Builder修饰。

@Builder function GloablMethodName() { ... }

而由于是全局的则不需要使用this来引用了

GloablMethodName()

如果不涉及组件状态变化，建议使用全局的自定义构建方法。

4、参数传递规则

自定义构建函数的参数传递有按值传递和按引用传递两种，均需遵守以下规则：

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

4.1、按引用传递参数

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

class Tmp {
  paramA1: string = ''
}

@Builder function overBuilder(params: Tmp) {
  Row() {
    Text(`UseStateVarByReference: ${params.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // Pass the this.label reference to the overBuilder component when the overBuilder component is called in the Parent component.
      overBuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // After Click me is clicked, the UI text changes from Hello to ArkUI.
        this.label = 'ArkUI';
      })
    }
  }
}

按引用传递参数时，如果在@Builder方法内调用自定义组件，ArkUI提供$$作为按引用传递参数的范式

class Tmp {
  paramA1: string = ''
}

@Builder function overBuilder($$: Tmp) {
  Row() {
    Column() {
      Text(`overBuilder===${$$.paramA1}`)
      HelloComponent({message: $$.paramA1})
    }
  }
}

@Component
struct HelloComponent {
  @Prop message: string;

  build() {
    Row() {
      Text(`HelloComponent===${this.message}`)
    }
  }
}

@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // Pass the this.label reference to the overBuilder component when the overBuilder component is called in the Parent component.
      overBuilder({paramA1: this.label})
      Button('Click me').onClick(() => {
        // After Click me is clicked, the UI text changes from Hello to ArkUI.
        this.label = 'ArkUI';
      })
    }
  }
}

4.2、按值传递参数

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

@Builder function overBuilder(paramA1: string) {
  Row() {
    Text(`UseStateVarByValue: ${paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      overBuilder(this.label)
    }
  }
}

二、@BuilderParam 装饰器（指向@Builder方法的变量的修饰器）

ArkUI引入了@BuilderParam装饰器，@BuilderParam用来装饰指向@Builder方法的变量（@BuilderParam是用来承接@Builder函数的），开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。

1、@BuilderParam 装饰器概述

@BuilderParam 装饰器用于将一个变量与 @Builder 方法关联起来，即定义一个变量并使用@BuilderParam修饰，初始化这个变量指向用@Builder修饰的一个方法。简单来说，它的作用是：

绑定方法：将一个变量绑定到一个 @Builder 方法，使得该变量可以作为参数传递。
复用 UI 元素：通过这个变量，可以在不同的地方复用同一个 @Builder 方法，提高代码的复用性和可维护性。
类型安全：确保变量的类型与 @Builder 方法的返回类型一致，增强代码的类型安全性。

@Component
struct MyComponent {
  // 定义一个 @Builder 方法，用于创建按钮
  @Builder createButton() {
    Button("点击我")
      .onClick(() => console.log("按钮被点击了"))
  }

  // 定义一个 @BuilderParam 变量，指向 createButton 方法
  @BuilderParam buttonBuilder: () => void = this.createButton;

  // 直接在 build 方法中调用 buttonBuilder 变量
  build() {
    Column() {
      this.buttonBuilder()  // 调用 buttonBuilder 变量，生成按钮
      Text("其他内容")
    }
  }
}

2、@BuilderParam 用法

2.1、绑定方法

@BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。@BuilderParam 修饰的变量可以正常调用其指向的 @Builder 方法。@BuilderParam 修饰的变量本质上是一个函数变量，它指向一个 @Builder 方法。因此，你可以像调用普通函数一样调用这个变量。如果在API 11中和@Require结合使用，则必须父组件构造传参。

使用所属自定义组件的自定义构建函数或者全局的自定义构建函数，在本地初始化@BuilderParam

@Builder function overBuilder() {}
@Component
struct Child {
  @Builder doNothingBuilder() {};

  // 使用自定义组件的自定义构建函数初始化@BuilderParam
  @BuilderParam customBuilderParam: () => void = this.doNothingBuilder;
  // 使用全局自定义构建函数初始化@BuilderParam
  @BuilderParam customOverBuilderParam: () => void = overBuilder;
  build(){}
}

用父组件自定义构建函数初始化子组件@BuilderParam装饰的方法

@Component
struct Child {
  @Builder customBuilder() {}
  // 使用父组件@Builder装饰的方法初始化子组件@BuilderParam
  @BuilderParam customBuilderParam: () => void = this.customBuilder;

  build() {
    Column() {
      this.customBuilderParam()
    }
  }
}
@Entry
@Component
struct Parent {
  @Builder componentBuilder() {
    Text(`Parent builder `)
  }
  build() {
    Column() {
      Child({ customBuilderParam: this.componentBuilder })
    }
  }
}

2.2、复用 UI 元素

假设我们有一个应用，其中包含多个页面，每个页面都需要显示一个相同的头部导航栏。我们可以使用 @Builder 和 @BuilderParam 装饰器来实现头部导航栏的复用。

@Component
struct MyApp {
  // 定义一个 @Builder 方法，表示这是一个用于构建 UI 元素的方法。创建一个包含应用标题和设置图标的头部导航栏。
  @Builder createHeader() {
    Row() {
      Text("我的应用")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      Spacer()
      Icon("settings_icon")
        .onClick(() => console.log("设置图标被点击了"))
    }
    .padding(10)
    .backgroundColor(Color.Gray)
  }

  // 定义一个 @BuilderParam 变量，被 @BuilderParam 装饰器标记，表示它是一个指向 createHeader 方法的变量。这个变量可以在其他地方作为参数传递，也可以直接调用。
  @BuilderParam headerBuilder: () => void = this.createHeader;

  // 定义首页组件，在 build 方法中调用 headerBuilder 变量，生成头部导航栏。
  @Component
  struct HomePage {
    build() {
      Column() {
        this.headerBuilder()  // 调用 headerBuilder 变量，生成头部导航栏
        Text("欢迎来到首页")
          .fontSize(18)
          .padding(20)
      }
    }
  }

  // 定义设置页组件，在 build 方法中调用 headerBuilder 变量，生成头部导航栏。
  @Component
  struct SettingsPage {
    build() {
      Column() {
        this.headerBuilder()  // 调用 headerBuilder 变量，生成头部导航栏
        Text("设置页面内容")
          .fontSize(18)
          .padding(20)
      }
    }
  }

  build() {
    TabBar() {
      TabItem("首页") {
        this.HomePage()
      }
      TabItem("设置") {
        this.SettingsPage()
      }
    }
  }
}