一、核心定位与设计目标

• 问题背景：在 V2 状态管理中，@Param 装饰的属性默认为只读（编译时报错 Cannot assign to 'xxx' because it is a read-only property），无法在子组件内部修改。而某些场景需在子组件内修改父组件传入的数据（如动态表单、自定义刷新控件），同时避免父组件后续更新覆盖子组件修改。
• 解决方案：@Once 作为辅助装饰器，与 @Param 搭配使用，实现：解除只读限制：允许子组件内部修改 @Param 属性；单次同步机制：仅接受父组件首次传入值，后续父组件数据变化不再同步到子组件。

二、核心机制与规则

1. 组合依赖

• 强制绑定：必须与 @Param 组合使用（单独使用或搭配其他装饰器均报错）：typescript// ✅ 正确 @Param @Once testContent: string = "默认值"; @Once @Param testContent2: string = "默认值"; // 顺序无关 // ❌ 错误（编译报错） @Local @Once testContent: string = "Hello"; // '@Once' works only with '@Param':cite[1]

2. 初始化特性

3. 修改权限

• 子组件可写：解除 @Param 的只读限制，支持在子组件内直接赋值并触发 UI 更新：typescriptButton("修改").onClick(() => { this.testContent = "新值"; // ✅ 允许修改（无 `@Once` 时报错） })

三、典型使用场景

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

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

typescript

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

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

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

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

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

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

typescript

// 开关控件子组件
@ComponentV2
struct ToggleSwitch {
  @Param @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 仅解决读写权限问题）。

五、迁移建议与最佳实践

1. 新旧方案对比

2. 使用原则

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

3. 替代方案警告

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

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

六、代码效果对比表

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