如何在鸿蒙 NEXT 中使用 @Builder 装饰器优化 UI 组件的复用？

2024-10-16
北京
本文字数：3012 字
阅读完需：约 10 分钟

在开发鸿蒙 NEXT 应用时，咱们需要经常创建自定义组件，由于自定义组件内部 UI 结构固定，仅与使用方进行数据传递，因此，ArkUI 还提供了一种更轻量的 UI 元素复用机制@Builder。

大家好，我是 V 哥，在鸿蒙 NEXT 开发中，@Builder 装饰器是一种轻量级的 UI 元素复用机制，它允许开发者将重复使用的 UI 元素抽象成一个方法，并在 build() 方法中多次调用，以实现 UI 结构的复用。以下是如何使用 @Builder 装饰器来优化 UI 组件复用的详细介绍和案例分析：

自定义构建函数

@Builder 方法可以定义在组件内或全局，用于封装可复用的 UI 结构。在组件内定义的 @Builder 方法可以通过 this 访问当前组件的属性和方法，而全局的 @Builder 方法则不能访问组件内部的属性和方法。

组件内 @Builder 方法：

@Entry@Componentstruct BuilderPage {  build() {    Column() {      Row({ space: 50 }) {        // 复用 UI 结构        this.compButtonBuilder($r('app.media.icon_edit'), '编辑', () => console.log('编辑'));        this.compButtonBuilder($r('app.media.icon_send'), '发送', () => console.log('发送'));      }    }.width('100%').height('100%').justifyContent(FlexAlign.Center);  }  // 定义 UI 结构  @Builder compButtonBuilder(icon: Resource, text: string, callback: () => void) {    Button() {      Row({ space: 10 }) {        Image(icon).width(25).height(25);        Text(text).fontColor(Color.White).fontSize(25);      }    }.width(120).height(50).onClick(callback);  }}

复制代码

在这个例子中，compButtonBuilder 是一个组件内的 @Builder 方法，它定义了一个按钮的 UI 结构，并在 build() 方法中被复用。

全局 @Builder 方法：

@Builder function globalButtonBuilder(icon: Resource, text: string, callback: () => void) {  Button() {    Row({ space: 10 }) {      Image(icon).width(25).height(25);      Text(text).fontColor(Color.White).fontSize(25);    }  }.width(120).height(50).onClick(callback);}
@Entry@Componentstruct BuilderPage {  build() {    Column() {      Row({ space: 50 }) {        // 复用 UI 结构        globalButtonBuilder($r('app.media.icon_edit'), '编辑', () => console.log('编辑'));        globalButtonBuilder($r('app.media.icon_send'), '发送', () => console.log('发送'));      }    }.width('100%').height('100%').justifyContent(FlexAlign.Center);  }}

复制代码

在这个例子中，globalButtonBuilder 是一个全局的 @Builder 方法，它被定义在组件外部，并通过 export 关键字导出，使其可以在应用的任何地方被调用。

参数传递规则

@Builder 方法具有两种参数传递机制——按值传递和按引用传递。当只有一个参数且参数为对象字面量时为按引用传递，其余情况均为按值传递。按引用传递时，若传递的参数为状态变量，则状态变量的变化会触发 @Builder 方法内部 UI 的刷新；按值传递时则不会。

`@BuilderParam` 装饰器

@BuilderParam 装饰器用于装饰自定义组件中的属性，使其可以作为 UI 结构的占位符。在创建组件时，可以通过参数为其传入具体的内容，类似于 Vue 框架中的 slot。

@Componentstruct Container {  @BuilderParam content: () => void  build() {    Column() {      Text('你好，我是V哥');      this.content(); // 占位符      Button('点我一下试试');    }  }}

复制代码

在这个例子中，content 是一个使用 @BuilderParam 装饰的属性，它可以在初始化自定义组件时被赋值，为自定义组件增加特定的功能。

@Builder 在购物车显示多个商品项的使用

让我们考虑一个电商应用中的购物车页面，这个页面需要显示多个商品项，每个商品项包括商品图片、名称、价格和数量选择器。我们希望商品项的 UI 是一致的，但每个商品项的具体内容（图片、名称、价格、数量）可能不同。这是一个典型的使用自定义组件的场景，我们可以通过@Builder装饰器来实现这一点。

步骤 1: 创建自定义组件

首先，我们创建一个名为CartItem的自定义组件，它将显示单个商品项的详细信息。

// CartItem.ets@Componentstruct CartItem {  @Prop商品图片: Resource;  @Prop商品名称: string;  @Prop商品价格: string;  @Prop商品数量: number;
  build() {    Row() {      Image(this.商品图片).width(50).height(50);      Column() {        Text(this.商品名称).fontSize(16);        Text(this.商品价格).fontSize(14).fontColor(Color.Red);      }      Stepper() {        Text(this.商品数量.toString())      }.min(1).max(10)    }    .padding(10).border({ width: 1, color: Color.Grey })  }}

复制代码

在这个组件中，我们使用了@Prop装饰器来定义属性，这些属性将由父组件传递。build()方法定义了商品项的 UI 结构。

步骤 2: 使用自定义组件

接下来，在购物车页面中使用CartItem组件来显示商品数据。

// CartPage.ets@Entry@Componentstruct CartPage {  @State商品列表: Array<{    商品图片: Resource;    商品名称: string;    商品价格: string;    商品数量: number;  }> = [    {      商品图片: $r('app.media.product1'),      商品名称: '商品名称1',      商品价格: '￥100',      商品数量: 1,    },    // 更多商品...  ];
  build() {    Column() {      ForEach(this.商品列表, (item) => {        CartItem({          商品图片: item.商品图片,          商品名称: item.商品名称,          商品价格: item.商品价格,          商品数量: item.商品数量,        })      })    }.padding(10)  }}

复制代码

在CartPage组件中，我们定义了一个状态变量商品列表来存储商品数据。在build()方法中，我们使用ForEach循环来遍历商品数组，并为每个商品创建一个CartItem组件实例，传递相应的属性。

详细解释一下

自定义组件的定义：CartItem组件通过@Component装饰器定义，使其成为一个自定义组件。它接受四个属性：商品图片、商品名称、商品价格和商品数量。
UI 布局：在CartItem的build()方法中，我们使用Row布局来水平排列商品图片、名称、价格和数量选择器。每个部分都设置了相应的样式，以确保布局的整洁和一致性。
属性传递：CartItem组件的属性是通过@Prop装饰器定义的，这允许父组件CartPage在创建CartItem实例时传递这些属性的值。
数据驱动：CartPage组件的状态变量商品列表包含了商品数据。使用ForEach循环，我们为每个商品项创建一个CartItem组件实例，并将商品数据作为属性传递给它。
重用性：CartItem组件是可重用的，因为它封装了商品项的 UI 和逻辑，可以在购物车页面之外的其他部分使用，只需传递相应的属性即可。

通过这个案例，我们可以看到如何使用自定义组件和@Builder装饰器来构建一个具有一致 UI 结构的电商应用购物车页面，同时保持代码的简洁性和可维护性。

小结一下

使用 @Builder 装饰器可以有效地复用 UI 结构，减少代码冗余，并提高开发效率。全局 @Builder 方法适用于整个应用中可复用的 UI 结构，而组件内的 @Builder 方法适用于特定组件内的复用。通过合理使用 @Builder 和 @BuilderParam 装饰器，开发者可以构建更加模块化和可维护的鸿蒙应用 UI 组件。轻舟已过万重山，鸿蒙势头不可挡。关注威哥爱编程，一起混进鸿蒙生态。

发布于: 刚刚阅读数: 3

原文链接:【http://xie.infoq.cn/article/753d67b6f0aedb2743ebf93a3】。

威哥爱编程

关注

华为 HDE、CSDN 博客专家、Java畅销书作者 2018-05-30 加入

全栈领域优质创作者（Java/HarmonyOS/AI），公众号：威哥爱编程

发布

暂无评论

创作场景

如何在鸿蒙 NEXT 中使用 @Builder 装饰器优化 UI 组件的复用？

自定义构建函数

参数传递规则

@BuilderParam 装饰器

@Builder 在购物车显示多个商品项的使用

步骤 1: 创建自定义组件

步骤 2: 使用自定义组件

详细解释一下

小结一下

威哥爱编程

评论

`@BuilderParam` 装饰器