HarmonyOS鸿蒙Next @Builder装饰器

HarmonyOS鸿蒙Next @Builder装饰器 在开始今天的分享前我们先回顾一下昨天的知识点：

  • 笼统的说就是可以创建可复用的UI组件逻辑，提升代码复用性。
  • 通过@Builder封装UI块，按需选择值/引用传递，最终引起直接响应状态。

OK，我们开始今天的分享。

今天分享的是参数传递规则

参数传递规则解析：

在自定义构建函数（@Builder）中，参数传递分为按值传递与按引用传递两种方式，需遵循以下核心规则：

1.参数类型严格匹配：

  • 传递的实参类型必须与形参声明类型完全一致。
  • 禁止传递 undefined、null 或返回这些值的表达式。

2.参数不可变形：

  • 在@Builder函数内部，禁止直接修改参数值（无论值传递还是引用传递）。

3.引用传递的特殊条件：

  • 仅当同时满足以下两点时，参数按引用传递：
    • 函数仅声明一个参数。
    • 调用时直接传入对象字面量（如 { data: this.value }）。
  • 其余场景（包括多参数、非对象字面量、状态变量直接传递等）默认按值传递。

4.值传递与状态变量的局限性：

  • 当使用按值传递方式传递状态变量（如 this.stateVar）时：
    • 状态变量的后续变化不会触发@Builder内部UI的自动刷新。
    • 更新仅依赖父组件的重新渲染（若父组件因状态变化触发build，会重新调用@Builder并传入新值）。
    • 推荐做法：若需实现@Builder内部UI随状态变量自动更新，应使用按引用传递（如通过 $stateVar 绑定引用）。

关键 差异 对比表：

下面是事例代码以及逐行解释：

1.按值传递参数
2.按引用传递参数

最后一段因为屏幕大小问题，所以我就挤了一下。

这块我们还是要说明一下：

  • 关键机制说明：

    • 引用传递生效条件：
      • 当且仅当同时满足：
        • 构建函数只接收单个参数
        • 调用时直接传入对象字面量（如{ paramA1: this.label }）
      • 此时参数会与源状态变量建立双向绑定
    • 状态更新流程：

  • 与值传递的本质差异：

    • 若改为overBuilder(new Tmp(this.label))（非对象字面量），则变为值传递
    • 此时点击按钮只会更新父组件的this.label，但不会触发overBuilder内部更新

  • 参数对象保护机制：

    • 虽然传递的是引用，但在@Builder函数内部直接修改params.paramA1是禁止的
    • 必须通过修改源状态变量（this.label）来触发更新。

OK，到这里就全部结束啦，欢迎大家的讨论。


更多关于HarmonyOS鸿蒙Next @Builder装饰器的实战教程也可以访问 https://www.itying.com/category-93-b0.html

2 回复

HarmonyOS的@Builder装饰器

@Builder装饰器是用于构建自定义UI组件的声明式描述方法。它允许开发者通过函数方式快速复用UI结构，支持参数传递和逻辑控制。

主要特点：

  1. 支持局部和全局两种Builder
  2. 可以嵌套使用多个@Builder
  3. 参数传递遵循TS/JS语法规则
  4. 能在组件内动态构建UI

典型用法：

[@Builder](/user/Builder)
function MyBuilder(param: string) {
  Text(param)
    .fontSize(20)
}

注意事项：

  1. 不能使用this关键字
  2. 不支持async/await
  3. 参数不能带默认值

更多关于HarmonyOS鸿蒙Next @Builder装饰器的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


关于HarmonyOS Next中@Builder装饰器的参数传递规则，有几个关键点需要注意：

  1. 参数传递方式的选择很重要：
  • 值传递适用于简单数据类型和不需要响应式更新的场景
  • 引用传递适合需要保持状态同步的复杂对象
  1. 引用传递的限制条件很严格：
  • 必须满足单参数+对象字面量的组合
  • 其他任何情况都会退化为值传递
  1. 状态更新机制差异明显：
  • 值传递不会自动触发UI更新
  • 引用传递能保持状态同步但不可直接修改参数
  1. 实际开发建议：
  • 需要响应式更新时优先考虑引用传递
  • 注意对象字面量的写法要求
  • 避免在@Builder内部直接修改参数

这些规则确保了组件状态管理的可控性和一致性，开发者需要根据具体场景选择合适的参数传递方式。

回到顶部