HarmonyOS 鸿蒙Next中【五】【V2装饰器】@Once：初始化同步一次=》

一、核心定位与设计目标

问题背景：

在 V2 状态管理中，@Param 装饰的属性默认为只读（编译时报错 Cannot assign to 'xxx' because it is a read-only property），无法在子组件内部修改。而某些场景需在子组件内修改父组件传入的数据（如动态表单、自定义刷新控件），同时避免父组件后续更新覆盖子组件修改。

解决方案：

[@Once](/user/Once) 作为辅助装饰器，与 @Param 搭配使用，实现：

• 解除只读限制：允许子组件内部修改 @Param 属性；
• 单次同步机制：仅接受父组件首次传入值，后续父组件数据变化不再同步到子组件。

// ✅ 正确
@Param [@Once](/user/Once) testContent: string = "默认值";
[@Once](/user/Once) @Param testContent2: string = "默认值"; // 顺序无关

// ❌ 错误（编译报错）
@Local [@Once](/user/Once) testContent: string = "Hello"; // '[@Once](/user/Once)' works only with '@Param':cite[1]

二、核心机制与规则

1. 组合依赖

强制绑定：

必须与 @Param 组合使用（单独使用或搭配其他装饰器均报错）：

// ✅ 正确
@Param [@Once](/user/Once) testContent: string = "默认值";
[@Once](/user/Once) @Param testContent2: string = "默认值"; // 顺序无关

// ❌ 错误（编译报错）
@Local [@Once](/user/Once) testContent: string = "Hello"; // '[@Once](/user/Once)' works only with '@Param':cite[1]

2. 初始化特性

3. 修改权限

子组件可写：

解除 @Param 的只读限制，支持在子组件内直接赋值并触发 UI 更新：

Button("修改").onClick(() => {
  this.testContent = "新值"; // ✅ 允许修改（无 `[@Once](/user/Once)` 时报错）
})

三、典型使用场景

场景 1：独立状态组件（父 → 子单向解耦）

需求：

父组件传递初始配置后，子组件内部状态独立运作（如自定义计时器、本地配置编辑器）。

// 父组件
@Entry
@ComponentV2
struct Parent {
  @Local config: string = "初始配置";

  build() {
    Child({ config: this.config }) // 仅首次传入生效
  }
}

// 子组件
@ComponentV2
struct Child {
  @Param [@Once](/user/Once) config: string = ""; // 父更新不覆盖子修改

  build() {
    Column() {
      Text(this.config)
      Button("内部修改").onClick(() => {
        this.config = "子组件修改值"; // ✅ 允许修改
      })
    }
  }
}

场景 2：自定义控件内部逻辑（避免父级干扰）

需求：

父组件传入初始值，子组件根据交互修改值且不触发父组件更新（如开关控件、评分组件）。

// 开关控件子组件
@ComponentV2
struct ToggleSwitch {
  @Param [@Once](/user/Once) isOn: boolean = false; // 父级更新不覆盖

  build() {
    Button(this.isOn ? "ON" : "OFF")
      .onClick(() => {
        this.isOn = !this.isOn; // ✅ 内部切换状态
      })
  }
}

四、技术限制与注意事项

1. 作用域限制：

   • 仅适用于 @ComponentV2 组件，V1 组件（@Component）不支持。

2. 序列化禁用：

   • @ObservedV2 类（常与 @Trace 搭配）无法使用 JSON.stringify() 序列化，混用时需避免。

3. 状态管理兼容性：

   • ❌ 禁止与 @State、@Link 等 V1 装饰器混用（编译/运行时报错）；
   • ❌ 不可搭配 @Local、@Provider 等 V2 装饰器。

4. 性能影响：

   • 深层嵌套对象修改时，需配合 @ObservedV2 + @Trace 实现精准更新（[@Once](/user/Once) 仅解决读写权限问题）。

五、迁移建议与最佳实践

1. 新旧方案对比

2. 使用原则

• 新项目：直接采用 @Param [@Once](/user/Once) 组合替代需内部修改的 @Prop 场景；
• 旧项目迁移：优先在独立组件中试点，逐步替换复杂回调逻辑。

3. 替代方案警告

若需持续同步父组件更新，应使用 @Param 单独修饰（无需 [@Once](/user/Once)）：

// 持续同步父级更新（非 [@Once](/user/Once) 场景）
@Param config: string; // 父级修改自动同步

六、代码效果对比表

通过 [@Once](/user/Once)，ArkTS 实现了父级初始值与子级独立状态的平衡，尤其适用于自定义控件、配置隔离等场景，是 V2 状态管理体系中解决数据所有权问题的关键工具。