【高心星出品】
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）。
![]()
@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 + 深拷贝 | 完全隔离 | 独立内存 | 需要数据隔离的安全场景 |
