ArkTS 状态管理 V2 — @Param 装饰器详解ArkTS 状态管理 V2

ArkTS 状态管理 V2 — `@Param` 装饰器详解

一起来构建生态吧~

@Param 是 HarmonyOS ArkTS 状态管理 V2 中用于 组件之间传递数据的关键装饰器，主要用于父组件向子组件单向传参，同时支持父组件状态变化自动同步到子组件。华为开发者官网

注：@Param 必须在 @ComponentV2 组件内部 使用才能生效。华为开发者官网

一、什么是 `@Param`？

@Param 是一个 属性装饰器，用于声明一个 可从父组件外部传入的参数。

子组件可以通过 @Param 接收父组件传入的数据。
当父组件传入的数据改变时，子组件内部对应的 @Param 值也会自动更新。
子组件不能直接修改 @Param 装饰的值（属于单向数据流）。华为开发者官网

二、核心特点与工作机制

1. 单向数据流（父 → 子）

@Param 变量基本遵循 单向数据流：

父组件将数据传入子组件；
子组件内部通过 this.xxx 访问传入值；
子组件不能直接修改该值；
当父组件状态改变时，子组件的参数值会同步更新。CSDN

2. 支持多种类型

@Param 支持多种类型的数据，包括：

基本类型：number / string / boolean 对象、类实例集合类型：Array / Map / Set / Date 甚至是联合类型 null / undefined 等等

它的接收机制是通用的。CSDN

3. 只读规则

在子组件中：

不能直接修改 @Param 装饰的属性；
若需要修改，可通过事件回调、父组件状态修改等 间接方式 完成。CSDN

4. 初始值规则

@Param 在子组件中允许 本地初始化默认值：

如果父组件传入参数，则优先使用父组件的值；
如果没有传入值，则使用本地初始化的默认值。CSDN

示例：

 @Param title: string = "默认标题";

5. 与 `@Require` 协作

如果某个 @Param 必须由父组件传入，可以配合 @Require 装饰器使用：

若父组件未传入该参数，在编译/运行时会报错或被提示必需传参。CSDN

 @Require @Param count: number;

三、常见使用场景示例

父子单向同步实例

 @ComponentV2
 struct Child {
   @Param count: number;
   build() {
     Text(`Child count: ${this.count}`);
   }
 }
 
 @ComponentV2
 struct Parent {
   @Local counter: number = 0;
 
   build() {
     Column() {
       Button(`Parent count: ${this.counter}`)
         .onClick(() => { this.counter++; });
 
       Child({ count: this.counter });
     }
   }
 }

说明：

Parent 通过属性对象把 counter 传给 Child；
每次父组件递增后，子组件自动更新显示。CSDN

带默认值的 `@Param`

 @ComponentV2
 struct Child {
   @Param title: string = "默认标题";
   build() {
     Text(this.title);
   }
 }
 
 Parent({ title: "来自父组件" });

结果：

如果父组件传入值，则覆盖默认值；
否则使用默认值。CSDN

复杂类型例子（数组同步）

 @ComponentV2
 struct ListChild {
   @Require @Param items: number[];
   build() {
     ForEach(this.items, (item) => Text(`${item}`));
   }
 }
 
 @ComponentV2
 struct ListParent {
   @Local arr: number[] = [1,2,3];
   build() {
     Column() {
       Button("Add")
         .onClick(() => { this.arr.push(this.arr.length + 1); });
       ListChild({ items: this.arr });
     }
   }
 }

说明：

此示例中，数组是引用类型。
子组件可观察数组本身，只要数组整体/内容变化，都会同步更新 UI。CSDN

四、规则总结与对比

特性	`@Param`（V2）
数据流方向	单向（父 → 子）
是否允许子组件赋值	❌ 不允许
支持默认本地初始值	✔️ 支持
与父组件状态同步	✔️ 支持
支持类型	基本/对象/数组等

五、与旧版 `@Prop` / `@State` 对比（简要）

与 V1 的 @Prop 类似，但更加安全和清晰；不允许子组件修改值，只能通过父组件更新，避免了数据冲突；与新的状态体系 (@Local, @Once, @Event) 协作更顺畅，使组件状态更易维护。CSDN

六、小结

@Param 是 构建现代 HarmonyOS 组件体系中不可缺少的部分：

实现组件之间类型安全的参数传递；保证数据单向流动、可预测性和可维护性；与父组件状态联动自动更新 UI；与 @Require、事件（@Event）机制协作可构建更复杂的交互模型。华为开发者官网+1

ArkTS 状态管理 V2 — @Param 装饰器详解