HarmonyOS 5.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)。

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

less 复制代码
@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 + 深拷贝 完全隔离 独立内存 需要数据隔离的安全场景
相关推荐
SWUT胖虎1 天前
AlphabetIndexer组件 与 List 联动总结
list·harmonyos·arkts·鸿蒙
鸿蒙小白龙1 天前
OpenHarmony轻量级内核LiteOS-M技术详解与应用实践
harmonyos·鸿蒙·鸿蒙系统·open harmony
Damon小智2 天前
HarmonyOS应用开发-低代码开发登录页面(超详细)
低代码·harmonyos·鸿蒙·登录·arcts·arcui·griditem
爱笑的眼睛112 天前
深入探讨HarmonyOS中ListItem的滑动操作:从基础实现到高级分布式交互
华为·harmonyos
摘星编程2 天前
【参赛心得】HarmonyOS创新赛获奖秘籍:如何用Stage模型和声明式UI打造高分作品
ui·华为·harmonyos·鸿蒙开发·stage模型
2501_919749032 天前
flutter鸿蒙:实现类似B站或抖音的弹幕功能
flutter·华为·harmonyos
鸿蒙小白龙2 天前
OpenHarmony后台服务开发指南:ServiceAbility与ServiceExtensionAbility全解析
harmonyos·鸿蒙系统·open harmony
浅蓝色2 天前
flutter平台判断,这次应该没问题了。支持鸿蒙,插件已发布
flutter·harmonyos
小雨青年2 天前
鸿蒙 HarmonyOS 6|ArkUI(03):状态管理
华为·harmonyos·1024程序员节
猫林老师3 天前
HarmonyOS分布式数据库深度应用
harmonyos