HarmonyOS 6.0 应用开发：V2 装饰器@once 使用详解

V2 装饰器@once 的使用

概念

在鸿蒙 ArkTS 开发中，@Once 装饰器用于实现子组件仅接受父组件传递的初始值，后续父组件数据变化不再同步至子组件。以下是其核心要点：

一、核心作用与规则

1. 初始化同步一次
   @Once 与 @Param 结合使用，子组件仅在初始化时接收父组件传递的值，后续父组件数据更新时不会触发同步。
2. 强制依赖关系
   • @Once 必须与 @Param 搭配使用，单独使用或与其他装饰器（如 @Local）结合会编译失败。
   • 装饰顺序不影响功能，@Param @Once 或 @Once @Param 均有效。
3. 本地修改支持
   结合 @Once 后，子组件可以修改 @Param 变量值并触发 UI 刷新，此时行为类似 @Local，但仍保留初始值传递能力。

二、适用场景

• 固定初始值：父组件传递配置参数（如主题色、默认尺寸），子组件仅需初始化时使用。
• 独立维护状态：子组件基于父组件初始值构建自身状态后，不再依赖外部更新。

案例

父组件（oncepage）： 点击按钮时，@Local 修饰的 count 自增，并通过 child3({ count: this.count }) 传递最新值给子组件。但子组件仅在首次渲染时接收初始值（如 10），后续父组件的 count 变化不会更新子组件。

子组件（child3）： 点击按钮时，子组件内部 count 自增并更新 UI，但父组件的 count 始终保持独立状态（例如父组件 count 为 15 时，子组件可能显示为 12）。

@ComponentV2 struct child3 {
  // 强制父组件传参 并且只会初始化一次
  @Require
  @Once
  @Param count: number

  build() {
    Column() {
      Button('child count: ' + this.count)
        .width('60%')
        .onClick(() => {
          // @once 装饰的变量 这里可以更新 count 值
          this.count += 1
        })
    }
    .width('100%')
    .padding(20)
  }
}

@Entry
@ComponentV2 struct oncepage {
  @Local count: number = 10

  build() {
    Column({ space: 20 }) {
      Button('page count: ' + this.count)
        .width('60%')
        .onClick(() => {
          this.count += 1
        })
      // child count 与 父组件 count 单向绑定
      child3({ count: this.count })
    }
    .height('100%')
    .width('100%')
  }
}

父子组件同步的数据为数组的时候，使用@once 和@param 修改数组中元素不会造成单向同步而是会形成双向同步效果，例如下面案例，父子组件数据会同时改变。

@ComponentV2 struct child4 {
  // 强制父组件传参 并且只会初始化一次
  @Require
  @Once
  @Param arr: number[]

  build() {
    Column() {
      Button('child count: ' + this.arr[0])
        .width('60%')
        .onClick(() => {
          // @once 装饰的变量 这里可以更新 count 值
          this.arr[0] += 1
        })
    }
    .width('100%')
    .padding(20)
  }
}

@Entry
@ComponentV2 struct oncepage1 {
  @Local arr: number[] = [1, 2, 3]

  build() {
    Column({ space: 20 }) {
      Button('page count: ' + this.arr[0])
        .width('60%')
        .onClick(() => {
          this.arr[0] += 1
        })
      // child count 与 父组件 count 单向绑定
      child4({ arr: this.arr })
      // 使用深度拷贝 就会造成隔离不会双向同步
      // child4({arr:[...this.arr]})
    }
    .height('100%')
    .width('100%')
  }
}

装饰器组合	同步方式	内存关系	适用场景
@Param	双向同步	共享引用	需要实时联动的组件（如协同编辑器）
@Once @Param	单次初始化同步	共享引用*	基于初始值的独立运作组件
@Param + 深拷贝	完全隔离	独立内存	需要数据隔离的安全场景