HarmonyOS 5.0 应用开发——V2 装饰器 @once 的使用

作者：高心星

2025-09-16
江苏
本文字数：1349 字
阅读完需：约 4 分钟

【高心星出品】

V2 装饰器 @once 的使用

概念

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

一、核心作用与规则

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

二、适用场景

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

案例

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

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

@ComponentV2struct 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@ComponentV2struct 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 修改数组中元素不会造成单向同步而是会形成双向同步效果，例如下面案例，父子组件数据会同时改变。

@ComponentV2struct 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@ComponentV2struct 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%')  }}