ArkTS @BuilderParam 基础用法使用总结

原创 于 2025-09-02 15:12:03 发布 · 143 阅读 · 0 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
GEO检测
标签
#鸿蒙系统 #harmonyos #鸿蒙 #html 
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ArkTS @BuilderParam 使用总结</title>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
        }
        body {
            background: linear-gradient(135deg, #1a2a6c, #b21f1f, #fdbb2d);
            color: #333;
            min-height: 100vh;
            padding: 20px;
            display: flex;
            flex-direction: column;
            align-items: center;
        }
        .container {
            max-width: 1200px;
            width: 100%;
            display: flex;
            flex-direction: column;
            gap: 30px;
        }
        header {
            background-color: rgba(255, 255, 255, 0.9);
            padding: 30px;
            border-radius: 15px;
            text-align: center;
            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
            margin-bottom: 20px;
        }
        h1 {
            color: #2c3e50;
            margin-bottom: 15px;
            font-size: 2.5rem;
        }
        .subtitle {
            color: #7f8c8d;
            font-size: 1.3rem;
            margin-bottom: 20px;
        }
        .content {
            display: flex;
            gap: 30px;
            flex-wrap: wrap;
        }
        .card {
            flex: 1;
            min-width: 300px;
            background: white;
            border-radius: 15px;
            overflow: hidden;
            box-shadow: 0 8px 20px rgba(0, 0, 0, 0.12);
            transition: transform 0.3s ease;
        }
        .card:hover {
            transform: translateY(-5px);
        }
        .card-header {
            background: #3498db;
            color: white;
            padding: 20px;
            font-weight: bold;
            font-size: 1.3rem;
            display: flex;
            align-items: center;
            gap: 10px;
        }
        .card-body {
            padding: 25px;
        }
        .card-body h3 {
            color: #2c3e50;
            margin-bottom: 15px;
            border-bottom: 2px solid #eee;
            padding-bottom: 10px;
        }
        pre {
            background: #f8f9fa;
            padding: 18px;
            border-radius: 8px;
            overflow-x: auto;
            margin: 18px 0;
            line-height: 1.5;
            font-size: 0.95rem;
            border-left: 4px solid #3498db;
        }
        code {
            font-family: 'Fira Code', monospace;
        }
        .explanation {
            margin-top: 18px;
            padding: 18px;
            background: #f1f8ff;
            border-radius: 8px;
            border-left: 4px solid #3498db;
        }
        .key-point {
            font-weight: bold;
            color: #2980b9;
        }
        .footer {
            margin-top: 40px;
            text-align: center;
            color: white;
            font-size: 1rem;
            padding: 20px;
            background: rgba(0, 0, 0, 0.2);
            border-radius: 10px;
            width: 100%;
        }
        .note {
            background: #fff3cd;
            border-left: 4px solid #ffc107;
            padding: 18px;
            margin: 18px 0;
            border-radius: 8px;
        }
        .icon {
            font-size: 1.5rem;
        }
        @media (max-width: 768px) {
            .content {
                flex-direction: column;
            }
            header {
                padding: 20px;
            }
            h1 {
                font-size: 2rem;
            }
        }
        .summary {
            background: white;
            border-radius: 15px;
            padding: 30px;
            box-shadow: 0 8px 20px rgba(0, 0, 0, 0.12);
        }
        .summary h2 {
            color: #2c3e50;
            margin-bottom: 20px;
            border-bottom: 2px solid #eee;
            padding-bottom: 10px;
        }
        .summary ul {
            list-style-type: none;
            padding: 0;
        }
        .summary li {
            padding: 12px;
            margin-bottom: 12px;
            background: #f8f9fa;
            border-radius: 8px;
            border-left: 4px solid #3498db;
            display: flex;
            align-items: center;
            gap: 10px;
        }
    </style>
</head>
<body>
    <div class="container">
        <header>
            <h1>ArkTS @BuilderParam 使用总结</h1>
            <p class="subtitle">全面掌握@BuilderParam的各种用法和场景</p>
        </header>
        
        <div class="content">
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-code icon"></i>
                    <span>基础用法</span>
                </div>
                <div class="card-body">
                    <h3>初始化@BuilderParam</h3>
                    <pre><code>@Builder
function overBuilder() {
}

@Component
struct Child {
  @Builder
  doNothingBuilder() {
  }

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

  build() {
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>@BuilderParam可以使用组件内部的@Builder函数或全局@Builder函数进行初始化。</p>
                    </div>
                </div>
            </div>
            
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-exchange-alt icon"></i>
                    <span>父子组件传参</span>
                </div>
                <div class="card-body">
                    <h3>父组件传递@Builder给子组件</h3>
                    <pre><code>@Component
struct Child {
  @BuilderParam customBuilderParam: () => void;
  
  build() {
    Column() {
      this.customBuilderParam()
    }
  }
}

@Entry
@Component
struct Parent {
  @Builder
  componentBuilder() {
    Text(`Parent builder `)
  }

  build() {
    Column() {
      Child({ customBuilderParam: this.componentBuilder })
    }
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>父组件可以将自己的@Builder函数传递给子组件的@BuilderParam，实现灵活的UI构建。</p>
                    </div>
                </div>
            </div>
            
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-project-diagram icon"></i>
                    <span>this指向问题</span>
                </div>
                <div class="card-body">
                    <h3>处理@Builder中的this指向</h3>
                    <pre><code>@Entry
@Component
struct Parent {
  label: string = 'Parent';

  @Builder
  componentBuilder() {
    Text(`${this.label}`)
  }

  build() {
    Column() {
      Child({
        // this指向子组件
        customBuilderParam: this.componentBuilder,
        // 使用箭头函数，this指向父组件
        customChangeThisBuilderParam: (): void => {
          this.componentBuilder()
        }
      })
    }
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>直接传递@Builder函数时，this指向接收组件；使用箭头函数包装时，this指向定义时的组件。</p>
                    </div>
                </div>
            </div>
        </div>
        
        <div class="content">
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-cogs icon"></i>
                    <span>参数传递</span>
                </div>
                <div class="card-body">
                    <h3>带参数的@Builder函数</h3>
                    <pre><code>class Tmp {
  label: string = '';
}

@Builder
function overBuilder($$: Tmp) {
  Text($$.label)
    .width(400)
    .height(50)
}

@Component
struct Child {
  // 有参数类型，指向的overBuilder也是有参数类型的方法
  @BuilderParam customOverBuilderParam: ($$: Tmp) => void = overBuilder;

  build() {
    Column() {
      this.customOverBuilderParam({ label: 'global Builder label' })
    }
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>@BuilderParam可以定义参数类型，并与相应签名的@Builder函数配合使用。</p>
                    </div>
                </div>
            </div>
            
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-code-branch icon"></i>
                    <span>尾随闭包</span>
                </div>
                <div class="card-body">
                    <h3>使用尾随闭包初始化@BuilderParam</h3>
                    <pre><code>@Component
struct CustomContainer {
  @Prop header: string = '';
  @BuilderParam closer: () => void;

  build() {
    Column() {
      Text(this.header)
        .fontSize(30)
      this.closer()
    }
  }
}

@Entry
@Component
struct CustomContainerUser {
  @State text: string = 'header';

  build() {
    Column() {
      // 使用尾随闭包{}初始化@BuilderParam
      CustomContainer({ header: this.text }) {
        Column() {
          Text('尾随闭包内容')
        }
      }
    }
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>通过在组件后紧跟大括号"{}"形成尾随闭包，可以初始化子组件的@BuilderParam。</p>
                    </div>
                </div>
            </div>
            
            <div class="card">
                <div class="card-header">
                    <i class="fas fa-mobile-alt icon"></i>
                    <span>页面级使用</span>
                </div>
                <div class="card-body">
                    <h3>在页面组件中使用</h3>
                    <pre><code>@ComponentV2
struct ChildPage {
  @Require @Param message: string = '';
  @BuilderParam customBuilderParam: () => void;

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
      this.customBuilderParam()
    }
  }
}

@Entry
@ComponentV2
struct ParentPage {
  @Local label: string = 'Parent Page';

  @Builder
  componentBuilder() {
    Text(`局部 Builder: ${this.label}`)
  }

  build() {
    Column() {
      ChildPage({ message: this.label }) {
        // 使用尾随闭包初始化@BuilderParam
        Column() {
          this.componentBuilder();
        }
      }
    }
  }
}</code></pre>
                    
                    <div class="explanation">
                        <p><span class="key-point">说明：</span>@BuilderParam在页面级组件中的使用方式类似，支持局部和全局@Builder函数。</p>
                    </div>
                </div>
            </div>
        </div>
        
        <div class="summary">
            <h2><i class="fas fa-check-circle"></i> @BuilderParam 使用要点总结</h2>
            <ul>
                <li><i class="fas fa-arrow-right"></i> <strong>初始化</strong>：可以使用组件内部的@Builder函数或全局@Builder函数初始化</li>
                <li><i class="fas fa-arrow-right"></i> <strong>传递方式</strong>：父组件可以通过属性传递@Builder函数给子组件的@BuilderParam</li>
                <li><i class="fas fa-arrow-right"></i> <strong>this指向</strong>：直接传递@Builder函数时，this指向接收组件；使用箭头函数时，this指向定义时的组件</li>
                <li><i class="fas fa-arrow-right"></i> <strong>参数传递</strong>：@BuilderParam可以定义参数类型，需要与相应签名的@Builder函数配合使用</li>
                <li><i class="fas fa-arrow-right"></i> <strong>尾随闭包</strong>：通过在组件后紧跟大括号"{}"形成尾随闭包，可以初始化子组件的@BuilderParam</li>
                <li><i class="fas fa-arrow-right"></i> <strong>使用场景</strong>：适用于需要动态定制组件部分UI的场景，提高组件的灵活性和复用性</li>
            </ul>
            
            <div class="note">
                <p><strong>最佳实践建议：</strong></p>
                <p>1. 明确@BuilderParam的函数签名，避免类型不匹配</p>
                <p>2. 注意this的指向问题，根据需要选择直接传递或使用箭头函数</p>
                <p>3. 对于复杂的UI构建，考虑使用带参数的@Builder函数</p>
                <p>4. 在组件文档中明确说明@BuilderParam的预期用途和参数要求</p>
            </div>
        </div>
        
        <div class="footer">
            <p>ArkTS @BuilderParam 使用总结 | 开发者指南与最佳实践</p>
        </div>
    </div>
</body>
</html>

ArkTS学习笔记_封装复用之@builderParam装饰器
诠释完美
07-14 667
【代码】ArkTS学习笔记_封装复用之@builderParam装饰器。
HarmonyOS/OpenHarmony应用开发-ArkTS语言@Builder自定义构建函数
weixin_69135651的博客
05-31 2053
ArkUI还提供了一种更轻量的UI元素复用机制@Builder，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build
HarmonyOS应用开发-ArkTS语言的装饰器之@BuilderParam
初一十五的博客
03-15 3350
@BuilderParam装饰器
HarmonyOS/OpenHarmony应用开发-ArkTS语言@BuilderParam引用@Builder函数
weixin_69135651的博客
05-30 1667
当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，ArkUI引入了@BuilderParam装饰器，@BuilderParam用来装饰指向@Builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。
HarmonyOS NEXT开发（Beta6）自定义组件@BuilderParam装饰器详解
wewqeqwrqw的博客
09-08 1369
​ @BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。如果在API 11中和@Require结合使用，则必须父组件构造传参。 ​
ArkTs 元素复用与传入@Builder @BuilderParam
juvenile_Li的博客
07-15 915
ArkUI提供了一种更轻量的UI元素复用机制 @Builder，可以将重复使用的UI元素抽象成一个方法，在 build 方法里调用。效果图可支持组件内和全局写法。
鸿蒙 harmonyOS：ArKTS @BuilderParam装饰器
2401_87008233的博客
04-06 1001
鸿蒙 ArKTS @BuilderParam装饰器 尾随闭包
鸿蒙HarmonyOS 5.0开发：ArkTS语言-@BuilderParam装饰器：引用@Builder函数
m0_73088370的博客
12-06 954
当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。
鸿蒙Harmony应用开发—ArkTS（@BuilderParam装饰器：引用@Builder函数）
m0_64420071的博客
03-22 2238
当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。
ArkTS中装饰器（@Builder / @Provide / @Observed）原理与实际用法！
欢迎来到菜鸟不学编程的博客
08-06 866
在鸿蒙系统中的ArkTS（Ark TypeScript）语言中，装饰器（decorator）作为一种语法特性，允许开发者在类或函数的定义上附加元数据或者修改它们的行为。ArkTS 中的装饰器，例如@Builder@Provide和@Observed，为开发者提供了更多的灵活性，能够简化代码、增强可读性，并促进更加声明式的编程风格。装饰器的工作原理通常依赖于 JavaScript/TypeScript 的反射机制，通过元数据附加、修改类的实例、方法的行为等。这些装饰器在鸿蒙的ArkUI。
ArkTs 复用并引用@Builder方法@Builder @BuilderParam（传入的方法带有参数输入）
m0_69294225的博客
08-27 869
这里 customBuilderParam: this.countMonthsCard 传入的参数错了，本来我写的是this.countMonthsCard（item:number）然后就报错了，后来传入的才是上面的但是显示数据只有数组的第一个元素然后我把countlist直接换成了一个数组输入进去又可以正常显示整个数组。主要是传入的参数要对，不然会出现奇奇怪怪的问题而且还不报错，以此记下一是提醒以后的自己，二是希望帮到有缘人（学艺不精还望海涵。
ArkTs中的@builder复用组件后修改数据不进行更新
weixin_55973411的博客
12-23 2065
按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起@Builder方法内的UI刷新。那是因为builder函数传入的数据是基本数据类型，不具备响应式的特点。那么此时复用的builde函数的参入也应该传入一个对象。作为按引用传递参数的范式。
Arkts中@Builder如何接收函数参数
2401_87105969的博客
11-26 630
类似这样的开发，我们常用的选择大多是List中嵌套ListItem，又或者是写一个Column布局然后用@Builder封装公用样式；不过不管怎么写，点击不同的操作肯定是进行不同的业务；那我们就可以给@Builder传入我们自定义的函数进去；首先需要一个对象用来存储我们的函数入参，因为官网文档中提到，@Builder接收按引用传递和按值传递，但是我们这儿两种都不是，所以需要包装一层对象；那这样，我们传入参数也变得简单了，只需要定义一个函数，然后new一个对象，将我们的函数当成一个属性传进去；
ArkTs装饰器之@Builder
weixin_58881409的博客
03-03 1071
ArkUI提供了一种轻量的UI元素复用机制@Builder，其内部UI结构固定，仅与使用方进行数据传递
[HarmonyOSNext鸿蒙开发]7.ArkUI进阶：@BuilderParam装饰器的核心用法与实战解析
qq_39277137的博客
05-20 1421
定位：用于装饰指向@Builder函数的变量，相当于UI元素的占位符（类似Vue的slot）解决的问题：避免自定义组件功能过度耦合，实现功能逻辑的动态注入兼容性：支持ArkTS卡片（API 9+）、元服务（API 11+）掌握@BuilderParam装饰器，意味着获得了组件动态化的金钥匙。3大核心使用模式2种作用域控制技巧5类常见问题解决方案开发者能够构建出高内聚、低耦合的鸿蒙组件体系。建议结合官方示例工程，在实践中深化对this指向、类型校验等关键概念的理解。
ArkTS中Builder与BuildParams深度解析：功能差异与最佳实践
最新发布
qq_42174884的博客
08-24 479
ArkTS组件开发中，Builder和BuildParams是两种核心代码组织方式。Builder适用于简单UI片段复用，通过函数式调用快速构建组件；BuildParams则适合复杂参数配置场景，提供更好的类型安全和可维护性。Builder在全局或组件内定义，支持灵活调用；BuildParams通过接口定义参数结构，处理复杂响应式数据更优。实际开发中可根据需求选择：简单UI优先使用Builder，复杂配置推荐BuildParams，二者也可混合使用以获得最佳开发效率。本文通过详细代码示例对比了两种方式的适用
ArkUI开发进阶—@Builder函数@BuilderParam装饰器的妙用与场景应用
一键难忘的博客
11-24 2489
为了更好地理解ArkTS的基本组成，我们将通过一个简单的示例来演示其语法和结构。在前文示例中，我们已经展示了如何在组件内使用@Builder装饰器创建自定义构建函数，并在组件的build方法中调用该函数，实现了对按钮的定制。接下来，我们将深入理解 @Builder 装饰器的一些重要概念。通过深入理解@Builder装饰器，我们可以更好地使用自定义构建函数来实现 UI 元素的复用，提高代码的可维护性和可读性。这一特性使得 ArkTS 在应用开发中更加灵活，让开发者能够更轻松地构建复杂的用户界面。
ArkTs中用@Builder定义组件和用@Component定义组件的区别
qq_67226268的博客
04-28 1032
是两种不同的组件定义方式，分别适用于不同的开发场景。类似于函数式组件，通常，@Builder用于标记一个函数作为构建器，生成UI内容，而@Component用于定义标准组件。是传统的组件定义方式，继承自Component，有生命周期和状态管理。在 ArkTS（HarmonyOS 应用开发语言）中，简化重复 UI 代码，提升开发效率。实际开发中，两者通常配合使用：用。管理核心状态和逻辑，用。
harmonyOS杂谈 - @Builder装饰器：自定义构建函数
weixin_42861217的博客
12-22 1231
全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。如果不涉及组件状态变化，建议使用全局的自定义构建方法。
第四讲_ArkTS装饰器（一）
wenqi1992的博客
01-18 1190
介绍@Builder和@BuilderParam装饰器
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值