HarmonyOS应用开发-@Builder装饰器详解

最新推荐文章于 2025-09-10 16:42:53 发布
原创 最新推荐文章于 2025-09-10 16:42:53 发布 · 2k 阅读 · 25 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #鸿蒙 #前端 #安卓

前言

前面章节介绍了如何创建一个自定义组件。该自定义组件内部UI结构固定，仅与使用方进行数据传递。ArkUI还提供了一种更轻量的UI元素复用机制@Builder，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。

为了简化语言，我们将@Builder装饰的函数也称为“自定义构建函数”。

装饰器使用说明

自定义组件内自定义构建函数

定义的语法

@Builder myBuilderFunc({ })

调用方法

this.myBuilderFunc()

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

全局自定义构建函数

定义的语法

@Builder function myGlobalBuilderFunc({ })

调用方法

myGlobalBuilderFunc()

●全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。
●如果不涉及组件状态变化，建议使用全局的自定义构建方法。

参数传递规则

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

●参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefine

最低0.47元/天 解锁文章
HarmonyOS：@Builder装饰器：自定义构建函数
ChinaDragon10的博客
01-06 2009
自定义构建函数的参数传递有按值传递和按引用传递两种，均需遵守以下规则： 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。 在@Builder修饰的函数内部，不允许改变参数值。 @Builder内UI语法遵循UI语法规则。 只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。
HarmonyOS自学-Day2(@Builder装饰器)
Richieeea的博客
12-19 1328
今天学习@Builder装饰器，@Builder所修饰的方法，就是一个包着UI元素的方法，在builder()方法中调用从而生成UI结构
鸿蒙：@Builder 和 @BuilderParam正确使用方法
2501_91974903的博客
09-10 437
这两个装饰器在鸿蒙中还是比较好用的，最近在整理代码的时候，用到了这两个装饰器，作用是插槽传组件、替换组件，相信有一些刚开始学习鸿蒙的朋友可能会有些迷糊。这里我就跟大家简单分享下。相信你看完了以后，应该能理解了。跟大家用白话讲讲，这个@Builder就类似于我们用的手机，@BuilderParam则类似于我们用的手机壳。假设你有多个手机，这个手机壳又恰好是通用的，那么你就可以。常见的是在自定义组件替换组件（
HarmonyOS/OpenHarmony应用开发-ArkTS语言@BuilderParam引用@Builder函数
weixin_69135651的博客
05-30 1635
当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，ArkUI引入了@BuilderParam装饰器，@BuilderParam用来装饰指向@Builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。
鸿蒙HarmonyOS开发：@Builder装饰器，自定义构建函数——UI结构复用
在这里，我乐于倾囊相授，分享我的技术心得、项目实战经验、技术技巧。希望能够惠及更多的开发者，助力大家在技术的海洋中扬帆远航。
05-16 3307
ArkUI还提供了一种更轻量的UI元素复用机制@Builder，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。为了简化语言，我们将@Builder装饰的函数也称为“自定义构建函数”。允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
鸿蒙开发笔记-4-装饰器之@Builder、@LocalBuilder、@BuilderParam、wrapBuilder
o118abcdef的博客
03-06 1607
Builder：适用于模块化UI复用，通过参数传递策略平衡灵活性与性能。：解决父子组件层级关系问题，适合动态内容插入。：实现组件插槽机制，提升UI组合能力。：动态构建器调用的终极方案，特别适合可视化搭建场景。
HarmonyOS NEXT开发（Beta6）自定义组件@LocalBuilder装饰器详解
wewqeqwrqw的博客
09-08 1413
为了解决组件的父子关系和状态管理的父子关系保持一致，引入@LocalBuilder装饰器。@LocalBuilder拥有和局部@Builder相同的功能，且比局部@Builder能够更好的确定组件的父子关系和状态管理的父子关系。
鸿蒙应用开发—@Builder装饰器：自定义构建函数
duoduola888的博客
06-19 528
允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。如果不涉及组件状态变化，建议使用全局的自定义构建方法。
23、鸿蒙学习——@Builder装饰器（自定义构建函数）
u010257931的博客
07-08 671
Entry@Component@Builder// @Builder装饰此函数，使其能以链式调用的方式配置并构建Text组件@Builderbuild() {Column() {// 无参数// 有参数允许在自定义组件内定义一个或多个@Builder函数，该函数被认为是该组件的私有、特殊类型的成员函数私有自定义构建函数允许在自定义组件内、build函数和其他自定义构建函数中使用在自定义组件中，this指代当前所属组件，组件的状态变量可在自定义构建函数内访问。
HarmonyOS NEXT开发（Beta6）自定义组件@BuilderParam装饰器详解
wewqeqwrqw的博客
09-08 1282
​ @BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。如果在API 11中和@Require结合使用，则必须父组件构造传参。 ​
鸿蒙开发：了解@Builder装饰器
知足常乐
02-14 998
@Builder装饰是鸿蒙UI开发中，非常重要的一个装饰器，在实际的开发中，合理且正确的使用，能够让我们的代码更加的简洁
鸿蒙5：自定义构建函数
qq_56760790的博客
06-29 1044
本文详细介绍了鸿蒙ArkTS语言中的自定义构建函数功能，主要包括： @Builder基础用法，通过构建函数复用UI元素 构建函数的参数传递方式（值传递和引用传递） 使用@BuilderParam实现UI插槽功能，在子组件中接收父组件传递的UI结构 通过Tabs组件案例展示@Builder的实际应用 尾随闭包的使用场景和注意事项 文章还提供了多个实践案例代码，如自定义TabBar、商品列表组件等，帮助开发者掌握如何灵活运用构建函数来优化鸿蒙应用开发。
如何在鸿蒙 NEXT 中使用 @Builder 装饰器优化 UI 组件的复用？
威哥爱编程，优快云 博客专家、全栈领域新星创作者、华为 HDE，愿交天下 IT 技术爱好者
10-16 716
Builder方法可以定义在组件内或全局，用于封装可复用的 UI 结构。在组件内定义的@Builder方法可以通过this访问当前组件的属性和方法，而全局的@Builder方法则不能访问组件内部的属性和方法。组件内@Builder方法@Entry@Componentbuild() {Column() {// 复用 UI 结构this.compButtonBuilder($r('app.media.icon_edit'), '编辑', () => console.log('编辑'));
鸿蒙Harmony应用开发—ArkTS（@Builder装饰器：自定义构建函数）
m0_64420071的博客
03-22 2650
该自定义组件内部UI结构固定，仅与使用方进行数据传递
鸿蒙开发入门：自定义组件--@BuilderParam装饰器
Android23333的博客
12-23 2895
允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。如果不涉及组件状态变化，建议使用全局的自定义构建方法。
鸿蒙开发笔记(四):自定义组件常用装饰器 @Builder @BuilderParam @Styles @Extend及stateStyles
Waruler的博客
01-16 4501
鸿蒙开发中自定义组件中常用的装饰器: @Builder @BuilderParam @Styles @Extend 及stateStyles
【鸿蒙开发】@Builder装饰器：自定义构建函数
d312697510的博客
04-08 1434
鸿蒙开发arkts，@Builder装饰器：自定义构建函数
【鸿蒙HarmonyOS开发笔记】组件编程技巧之使用@Builder装饰器实现UI结构复用
温的打怪之旅
03-18 5241
当页面有多个相同的UI结构时，若每个都单独声明，同样会有大量重复的代码。为避免重复代码，可以将相同的UI结构提炼为一个自定义组件，完成UI结构的复用。除此之外，ArkTS还提供了一种更轻量的UI结构复用机制@Builder方法，开发者可以将重复使用的UI元素抽象成一个@Builder方法，该方法可在build()方法中调用多次，以完成UI结构的复用。@Builder方法和自定义组件虽然都可以实现UI复用的效果，但是两者还是有着本质的区别的，其中最为显著的一个区别就是自定义组件可以定义自己的状态变量，而。
鸿蒙应用开发-组件构建函数
m0_56255097的博客
02-29 1392
在一些系统组件中，根据配置无法达到预期UI，可以使用 @Builder 构建函数自定义UI，前提该组件支持自定义。在一些系统组件中，根据配置无法达到预期UI，可以使用@Builder构建函数自定义UI，前提该组件支持自定义。需求：自定义Tabs组件的TabBarUI结构@Entry@Component@State{ defaultIcon: $r('app.media.home'), activeIcon: $r('app.media.home_select'), label: '首页' },
@Builder装饰器：自定义构建函数的使用
最新发布
11-15
<think> 我们正在讨论的是ArkTS中的@Builder装饰器，用于自定义构建函数。根据引用内容，我们可以总结如下： 1. @Builder装饰器用于创建自定义构建函数，可以将重复的UI结构抽象成一个方法。 2. @Builder装饰的函数遵循build()函数的语法规则。 3. @Builder有两种类型：自定义组件内定义的私有@Builder（只能在组件内调用）和全局的@Builder（可以在整个应用内调用）。 4. 参数传递方式：默认按值传递，但为了在传递状态变量时能够触发UI刷新，推荐使用按引用传递（使用'$'符号）。 下面将详细介绍使用方法，包括基本使用、参数传递、在组件内定义和全局定义等。 ### 1. 基本使用方法 #### 1.1 组件内私有@Builder 在自定义组件内使用`@Builder`装饰一个函数，该函数可以在组件的build函数或其他自定义构建函数中调用。 ```typescript @Entry @Component struct MyComponent { @Builder myBuilderFunction() { // 在这里构建UI Column() { Text('Hello, Builder!') .fontSize(20) Button('Click me') .onClick(() => { // 点击事件 }) } } build() { Column() { // 调用自定义构建函数 this.myBuilderFunction() } } } ``` #### 1.2 全局@Builder 在组件外定义的@Builder函数是全局的，可以在任意组件中调用。 ```typescript // 全局自定义构建函数 @Builder function GlobalBuilder() { Row() { Text('Global Builder') .fontColor(Color.Blue) } } @Entry @Component struct MyComponent { build() { Column() { // 调用全局构建函数 GlobalBuilder() } } } ``` ### 2. 参数传递 #### 2.1 按值传递（默认） 默认情况下，@Builder函数的参数是按值传递的。这意味着当传递的状态变量发生变化时，不会触发@Builder函数内部的UI刷新。 ```typescript @Builder function ValueTransferBuilder(paramA: string) { Row() { Text(`参数值: ${paramA}`) } } @Entry @Component struct ParentComponent { @State message: string = '初始值' build() { Column() { // 按值传递，message的变化不会触发Builder内部更新 ValueTransferBuilder(this.message) Button('改变值').onClick(() => { this.message = '新值' }) } } } ``` 点击按钮后，虽然`message`状态改变了，但`ValueTransferBuilder`中显示的文本不会更新。 #### 2.2 按引用传递 为了能够响应状态变化，需要使用按引用传递，在参数名前加上`$`符号。 ```typescript @Builder function ReferenceTransferBuilder($paramA: string) { Row() { Text(`参数值: ${$paramA}`) // 当paramA变化时，这里会更新 } } @Entry @Component struct ParentComponent { @State message: string = '初始值' build() { Column() { // 按引用传递，message变化会触发Builder内部更新 ReferenceTransferBuilder($$this.message) Button('改变值').onClick(() => { this.message = '新值' }) } } } ``` 注意：在调用时，我们使用`$$`来传递状态变量的引用（在ArkTS中，按引用传递的语法是`$$变量名`）。这样，当状态变量`message`改变时，构建函数内部也会更新。 ### 3. 在@Builder中访问组件状态 在组件内的@Builder函数中，可以直接通过`this`访问组件的状态变量。 ```typescript @Entry @Component struct MyComponent { @State count: number = 0 @Builder CounterBuilder() { // 直接使用this.count访问组件的状态变量 Button(`点击次数: ${this.count}`) .onClick(() => { this.count++ // 修改状态，会触发UI更新 }) } build() { Column() { this.CounterBuilder() } } } ``` ### 4. 组合使用多个@Builder 自定义构建函数可以相互调用，实现更复杂的UI复用。 ```typescript @Entry @Component struct MyComponent { @Builder HeaderBuilder(title: string) { Text(title) .fontSize(30) .fontWeight(FontWeight.Bold) } @Builder FooterBuilder() { Text('底部信息') .fontSize(14) .fontColor(Color.Gray) } @Builder ContentBuilder() { Column() { this.HeaderBuilder('主标题') Text('这里是内容区域...') this.FooterBuilder() } } build() { Column() { this.ContentBuilder() } } } ``` ### 总结 使用@Builder装饰器可以有效地复用UI代码，提高开发效率。关键点包括： - 私有@Builder在组件内定义，全局@Builder在组件外定义。 - 默认按值传递参数，若希望响应状态变化，需使用按引用传递（在参数前加`$`，并使用`$$`传递状态变量）。 - 在组件内的@Builder中，可以通过`this`访问组件的状态变量。 通过合理使用@Builder，可以构建出结构清晰、易于维护的UI代码。 [^1]: HarmonyOS开发者文档中心 - ArkTS @Builder装饰器 [^2]: OpenHarmony实战——自定义构建函数：@Builder装饰器 [^3]: ArkTS @Builder装饰器：自定义构建函数 [^4]: 构建ArkTS之@Builder装饰器：自定义构建函数 §§相关问题§§ 1. 如何理解ArkTS中@Builder装饰器的按引用传递？ 2. 全局@Builder和组件内@Builder有什么区别？ 3. 在@Builder中如何访问外部组件的状态变量？ 4. @Builder装饰器与自定义组件有何异同？ 5. 如何避免在@Builder中产生不必要的UI刷新？ </think>### @Builder装饰器的使用方法详解 @Builder是ArkUI提供的轻量级UI元素复用机制，用于创建可复用的UI构建函数。以下是具体使用方法： #### 1. **基本定义语法** ```typescript // 组件内私有构建函数 @Builder myBuilder() { // UI结构 } // 全局构建函数 @Builder function GlobalBuilder() { // UI结构 } ``` #### 2. **组件内私有构建函数** 在自定义组件内部使用，通过`this`访问组件状态： ```typescript @Component struct MyComponent { @State counter: number = 0 // 私有构建函数 @Builder CounterButton() { Button(`点击 ${this.counter}`) .onClick(() => this.counter++) .margin(10) } build() { Column() { this.CounterButton() // 调用构建函数 this.CounterButton() // 复用UI } } } ``` #### 3. **全局构建函数** 定义在组件外部，可在任意组件中调用： ```typescript // 全局构建函数[^2] @Builder function RedButton(label: string) { Button(label) .backgroundColor(Color.Red) .fontColor(Color.White) } @Entry @Component struct HomePage { build() { Column() { RedButton('警告') // 全局调用 RedButton('危险') } } } ``` #### 4. **参数传递方式** - **按值传递**（默认）：状态变量更新不会触发UI刷新 ```typescript @Builder function StaticBuilder(param: string) { Text(param) // 不会响应外部变化 } ``` - **按引用传递**（推荐）：使用`$`前缀响应状态变化[^3] ```typescript @Builder function DynamicBuilder($param: string) { Text($param) // 响应外部状态变化 } // 调用时 DynamicBuilder($$this.stateVar) ``` #### 5. **最佳实践** 1. **访问组件状态**：在私有构建函数中直接通过`this`访问 ```typescript @Builder ThemeButton() { Button(this.buttonText) // 直接访问组件状态 .backgroundColor(this.themeColor) } ``` 2. **组合使用**：构建函数可嵌套调用 ```typescript @Builder FormItem(label: string) { Row() { Text(label).width('30%') RedButton('提交') // 调用其他构建函数 } } ``` 3. **样式分离**：与@Styles配合使用 ```typescript @Styles function cardStyle() { .padding(10) .backgroundColor(Color.White) } @Builder function InfoCard() { Column() { // 内容 }.style(cardStyle) // 应用样式 } ``` #### 6. **与自定义组件的区别** | 特性 | @Builder构建函数 | 自定义组件 | |--------------|-----------------------|-------------------| | 复用粒度 | UI片段 | 完整组件 | | 状态管理 | 依赖父组件状态 | 自有状态管理 | | 生命周期 | 无 | 完整生命周期 | | 参数传递 | 灵活的直接参数传递 | 通过属性参数传递 | | 最佳场景 | 简单UI复用 | 复杂独立功能模块 | [^1]: HarmonyOS开发者文档中心 - @Builder装饰器 [^2]: OpenHarmony实战 - 自定义构建函数 [^3]: ArkTS @Builder参数传递规范 [^4]: 构建ArkTS之@Builder装饰器
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值