文章目录一、引言二、什么是 Param2.1 核心特点三、基础用法从父组件传递数据3.1 父组件定义状态并传递3.2 子组件使用 Param 接收数据3.3 运行效果四、进阶用法Once 与 Event4.1 Once仅初始化时接收4.2 Event子组件通知父组件修改五、使用提示与最佳实践六、总结一、引言在鸿蒙HarmonyOS应用开发中状态管理是构建动态、可交互界面的核心。随着 API 12 及后续版本对ComponentV2装饰器的引入状态管理变得更加简洁和高效。其中Param装饰器是子组件接收父组件数据的关键桥梁。二、什么是 ParamParam是鸿蒙状态管理 V2 版本ComponentV2中用于接收外部传入数据的装饰器。它的核心作用是让子组件能够从父组件获取单向同步的数据。当父组件的数据源发生变化时子组件中对应Param装饰的变量会自动更新并刷新 UI。2.1 核心特点单向数据流数据只能从父组件流向子组件子组件不能直接修改Param变量只读。若需要修改可搭配Event或Once使用。灵活初始化支持本地默认值但若从父组件传入了值则优先使用外部传入的值。未初始化时必须配合Require使用强制要求外部传入。广泛的数据类型支持可以装饰number、string、boolean、Object、class、Array、Set、Map、Date等也支持null、undefined和联合类型。简化 V1 状态管理相比 V1 的Prop、Link、ObjectLink等装饰器Param使用方式更统一减少了选择困难和性能问题。三、基础用法从父组件传递数据下面通过一个简单的计数器示例展示Param的基本用法。3.1 父组件定义状态并传递父组件使用Local定义本地状态并通过子组件的构造参数将数据传递下去。// 父组件EntryComponentV2struct Parent{Localcount:number0;build(){Column(){Text(父组件 count:${this.count}).fontSize(20)Button(增加).onClick((){this.count;})Child({value:this.count})// 将 count 传入子组件}.width(100%).height(100%)}}3.2 子组件使用 Param 接收数据子组件使用Require Param声明一个必须从外部传入的属性。// 子组件ComponentV2struct Child{RequireParamvalue:number;// 必须从外部传入build(){Column(){Text(子组件接收的 value:${this.value}).fontSize(20).onClick((){// ❌ Cannot assign to value because it is a read-only property. ArkTSCheck// this.value 1;})}}}3.3 运行效果每次点击父组件中的“增加”按钮count增加子组件中value的显示会随之更新。重点子组件内无法对this.value重新赋值尝试赋值会报编译错误保证了数据流的单向性和可预测性。上面示例中传递的是基本数据类型如需传递引用数据类型需要配合 ObservedV2 Trace。四、进阶用法Once 与 Event4.1 Once仅初始化时接收若只需在初始化时接收一次值后续不再随父组件更新可搭配Once使用。Once是鸿蒙状态管理 V2 中与Param配合使用的装饰器用于标记某个参数仅在组件初始化时接收一次父组件传入的值。一旦组件创建完成即使父组件的数据源后续发生变化子组件中Once装饰的变量也不会再更新从而避免不必要的 UI 刷新提升性能。ComponentV2struct Child{ParamOnceinitialValue:string默认值;build(){Text(this.initialValue)}}4.2 Event子组件通知父组件修改若需要在子组件内修改外部数据可通过Event装饰回调函数让子组件“通知”父组件执行修改从而保持数据和 UI 的一致性。Event是鸿蒙状态管理 V2 中用于定义事件回调的装饰器。它允许父组件将方法作为回调传递给子组件子组件通过调用该回调来“通知”父组件执行修改操作从而在保持单向数据流的前提下实现子组件对父组件数据的间接修改。// 父组件EntryComponentV2struct Parent{Localcount:number0;// 定义一个修改 count 的方法incrementCount(){this.count;}build(){Column(){Text(父组件 count:${this.count})Child({value:this.count,onIncrement:(){this.incrementCount()}})}}}// 子组件ComponentV2struct Child{RequireParamvalue:number;RequireEventonIncrement:()void;// 接收一个事件回调build(){Column(){Text(子组件 value:${this.value})Button(子组件请求增加).onClick((){this.onIncrement();// 调用父组件的方法})}}}五、使用提示与最佳实践优先使用 Param在 V2 架构中Param是子组件接收外部数据的首选方式它比 V1 的Prop更简洁、性能更好。配合 Require 使用如果Param变量没有设置默认值必须加上Require装饰器强制父组件传入该参数避免运行时错误。避免在子组件内修改 Param保持数据流的单向性有助于代码的可维护性和可预测性。如需修改请使用Event回调。合理使用 Once对于只需要初始化一次的数据如配置项、静态文本使用Once可以避免不必要的 UI 刷新提升性能。六、总结Param是鸿蒙ComponentV2状态管理体系中的基石。它通过强制单向数据流让组件间的数据传递变得清晰、可预测。结合Once和Event你可以构建出既灵活又健壮的组件树。