摘要
在鸿蒙 NEXT 开发中,@Builder
装饰器是一种轻量级的 UI 元素复用机制,它允许开发者将重复使用的 UI 元素抽象成一个方法,并在 build()
方法中多次调用,以实现 UI 结构的复用。以下是如何使用 @Builder
装饰器来优化 UI 组件复用的详细介绍和案例分析:
自定义构建函数
@Builder 方法可以定义在组件内或全局,用于封装可复用的 UI 结构。在组件内定义的 @Builder 方法可以通过 this 访问当前组件的属性和方法,而全局的 @Builder 方法则不能访问组件内部的属性和方法。
组件内 @Builder 方法:
TypeScript
@Entry
@Component
struct 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);
}
}
全局 @Builder 方法:
TypeScript
@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
@Component
struct 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);
}
}
参数传递规则
@Builder 方法具有两种参数传递机制------按值传递和按引用传递。当只有一个参数且参数为对象字面量时为按引用传递,其余情况均为按值传递。按引用传递时,若传递的参数为状态变量,则状态变量的变化会触发 @Builder 方法内部 UI 的刷新;按值传递时则不会。
@BuilderParam 装饰器
@BuilderParam 装饰器用于装饰自定义组件中的属性,使其可以作为 UI 结构的占位符。在创建组件时,可以通过参数为其传入具体的内容,类似于 Vue 框架中的 slot。
TypeScript
@Component
struct Container {
@BuilderParam content: () => void
build() {
Column() {
Text('你好,我是V哥');
this.content(); // 占位符
Button('点我一下试试');
}
}
}
@Builder 在购物车显示多个商品项的使用
让我们考虑一个电商应用中的购物车页面,这个页面需要显示多个商品项,每个商品项包括商品图片、名称、价格和数量选择器。我们希望商品项的UI是一致的,但每个商品项的具体内容(图片、名称、价格、数量)可能不同。这是一个典型的使用自定义组件的场景,我们可以通过@Builder装饰器来实现这一点。
步骤 1: 创建自定义组件
首先,我们创建一个名为CartItem
的自定义组件,它将显示单个商品项的详细信息。
TypeScript
// CartItem.ets
@Component
struct 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
组件来显示商品数据。
TypeScript
// CartPage.ets
@Entry
@Component
struct 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组件实例,传递相应的属性。
通过这个案例,我们可以看到如何使用自定义组件和@Builder装饰器来构建一个具有一致UI结构的电商应用购物车页面,同时保持代码的简洁性和可维护性。
总结
使用 @Builder 装饰器可以有效地复用 UI 结构,减少代码冗余,并提高开发效率。全局 @Builder 方法适用于整个应用中可复用的 UI 结构,而组件内的 @Builder 方法适用于特定组件内的复用。通过合理使用 @Builder 和 @BuilderParam 装饰器,开发者可以构建更加模块化和可维护的鸿蒙应用 UI 组件。