一、概述
为增强子组件接受外部参数输入的能力，开发者可使用@Param装饰器。从API version 12开始，在@ComponentV2装饰的自定义组件中支持使用@Param装饰器。当前状态管理（V2试用版）相关功能尚未成熟，建议开发者尝鲜试用。
（一）功能特点
- 表示外部传入状态：使得父子组件之间的数据能够进行同步。
- 变量初始化：支持本地初始化，但不允许在组件内部直接修改变量本身（对于对象类型的变量，可修改其内部属性）。若不在本地初始化，则需和
@Require装饰器一起使用，要求必须从外部传入初始化。 - 同步类型：由父到子单向同步。
- 接受多种数据源：可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等，同时支持
null、undefined以及联合类型。 - 触发UI刷新：
@Param装饰的变量变化时，会刷新该变量关联的组件。
（二）与状态管理V1版本装饰器对比
状态管理V1版本常用的可接受外部传入的装饰器（如@State、@Prop、@Link、@ObjectLink）存在使用限制多、不易区分的问题，使用不当时还会导致性能问题。例如@State仅能在初始化时获得引用，改变后无法同步；@Prop单向同步复杂类型时深拷贝性能差；@Link要求数据源也是状态变量；@ObjectLink要求属性类型为@Observed装饰的类。因此推出@Param装饰器简化父子组件传值规则。
二、装饰器说明
（一）变量装饰器参数
无参数。
（二）能否本地修改
否，修改值需使用@Event装饰器的能力（对于对象类型变量，可修改其内部属性）。
（三）同步类型
由父到子单向同步。
（四）允许装饰的变量类型
包括Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型，支持null、undefined以及联合类型。
（五）被装饰变量的初始值
允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。当同时存在本地初始值与外部传入值时，优先使用外部传入值进行初始化。
三、变量传递规则
（一）从父组件初始化
@Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。
（二）初始化子组件
@Param装饰的变量可以初始化子组件中@Param装饰的变量。
（三）同步
@Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。
四、观察变化
（一）基本类型（boolean、string、number）
可以观察来自数据源同步的变化。例如：
@Entry
@ComponentV2
struct Index {@Local count: number = 0;@Local message: string = "Hello";@Local flag: boolean = false;build() {Column() {Text(`Local ${this.count}`)Text(`Local ${this.message}`)Text(`Local ${this.flag}`)Button("change Local").onClick(() => {// 对数据源的更改会同步给子组件this.count++;this.message += " World";this.flag =!this.flag;})Child({count: this.count,message: this.message,flag: this.flag})}}
}
@ComponentV2
struct Child {@Require @Param count: number;@Require @Param message: string;@Require @Param flag: boolean;build() {Column() {Text(`Param ${this.count}`)Text(`Param ${this.message}`)Text(`Param ${this.flag}`)}}
}
（二）类对象
仅可以观察到对类对象整体赋值的变化，无法直接观察到对类成员属性赋值的变化，对类成员属性的观察依赖@ObservedV2和@Trace装饰器。例如：
class RawObject {name: string;constructor(name: string ) {this.name = name;}
}
@ObservedV2
class ObservedObject {@Trace name: string;constructor(name: string ) {this.name = name;}
}
@Entry
@ComponentV2
struct Index {@Local rawObject: RawObject = new RawObject("rawObject");@Local observedObject: ObservedObject = new ObservedObject("observedObject");build() {Column() {Text(`${this.rawObject.name}`)Text(`${this.observedObject.name}`)Button("change object").onClick(() => {// 对类对象整体的修改均能观察到this.rawObject = new RawObject("new rawObject");this.observedObject = new ObservedObject("new observedObject");})Button("change name").onClick(() => {// @Local与@Param均不具备观察类对象属性的能力，因此对rawObject.name的修改无法观察到this.rawObject.name = "new rawObject name";// 由于ObservedObject的name属性被@Trace装饰，因此对observedObject.name的修改能被观察到this.observedObject.name = "new observedObject name";})Child({rawObject: this.rawObject,observedObject: this.observedObject})}}
}
@ComponentV2
struct Child {@Require @Param rawObject: RawObject;@Require @Param observedObject: ObservedObject;build() {Column() {Text(`${this.rawObject.name}`)Text(`${this.observedObject.name}`)}}
}
（三）简单类型数组
可以观察到数组整体或数组项的变化。例如：
@Entry
@ComponentV2
struct Index {@Local numArr: number[] = [1,2,3,4,5];@Local dimensionTwo: number[][] = [[1,2,3],[4,5,6]];build() {Column() {Text(`${this.numArr[0]}`)Text(`${this.numArr[1]}`)Text(`${this.numArr[2]}`)Text(`${this.dimensionTwo[0][0]}`)Text(`${this.dimensionTwo[1][1]}`)Button("change array item").onClick(() => {this.numArr[0]++;this.numArr[1] += 2;this.dimensionTwo[0][0] = 0;this.dimensionTwo[1][1] = 0;})Button("change whole array").onClick(() => {this.numArr = [5,4,3,2,1];this.dimensionTwo = [[7,8,9],[0,1,2]];})Child({numArr: this.numArr,dimensionTwo: this.dimensionTwo})}}
}
@ComponentV2
struct Child {@Require @Param numArr: number[];@Require @Param dimensionTwo: number[][];build() {Column() {Text(`${this.numArr[0]}`)Text(`${this.numArr[1]}`)Text(`${this.numArr[2]}`)Text(`${this.dimensionTwo[0][0]}`)Text(`${this.dimensionTwo[1][1]}`)}}
}
（四）嵌套类或对象数组
@Param无法观察深层对象属性的变化，对深层对象属性的观测依赖@ObservedV2与@Trace装饰器。例如：
@ObservedV2
class Region {@Trace x: number;@Trace y: number;constructor(x: number, y: number) {this.x = x;this.y = y;}
}
@ObservedV2
class Info {@Trace region: Region;@Trace name: string;constructor(name: string, x: number, y: number ) {this.name = name;this.region = new Region(x, y);}
}
@Entry
@ComponentV2
struct Index {@Local infoArr: Info[] = [new Info("Ocean", 28, 120), new Info("Mountain", 26, 20)];@Local originInfo: Info = new Info("Origin", 0, 0);build() {Column() {ForEach(this.infoArr, (info: Info) => {Row() {Text(`name: ${info.name}`)Text(`region: ${info.region.x}-${info.region.y}`)}})Row() {Text(`Origin name: ${this.originInfo.name}`)Text(`Origin region: ${this.originInfo.region.x}-${this.originInfo.region.y}`)}Button("change infoArr item").onClick(() => {// 由于属性name被@Trace装饰，所以能够观察到this.infoArr[0].name = "Win";})Button("change originInfo").onClick(() => {// 由于变量originInfo被@Local装饰，所以能够观察到this.originInfo = new Info("Origin", 100, 100);})Button("change originInfo region").onClick(() => {// 由于属性x、y被@Trace装饰，所以能够观察到this.originInfo.region.x = 25;this.originInfo.region.y = 25;})}}
}
@ComponentV2
struct Child {@Param infoArr: Info[] = [];@Param originInfo: Info = new Info("O", 0, 0);build() {Column() {ForEach(this.infoArr, (info: Info) => {Row() {Text(`name: ${info.name}`)Text(`region: ${info.region.x}-${info.region.y}`)}})Row() {Text(`Origin name: ${this.originInfo.name}`)Text(`Origin region: ${this.originInfo.region.x}-${this.originInfo.region.y}`)}}}
}
（五）内置类型（Array、Date、Map、Set）
- Array：可以观察到变量整体赋值以及通过API调用（如
push、pop、shift、unshift、splice、copyWithin、fill、reverse、sort）带来的变化。 - Date：可以观察到数据源对
Date整体的赋值，以及调用Date的接口（如setFullYear、setMonth、setDate、setHours、setMinutes、setSeconds、setMilliseconds、setTime、setUTCFullYear、setUTCMonth、setUTCDate、setUTCHours、setUTCMinutes、setUTCSeconds、setUTCMilliseconds）带来的变化。 - Map：可以观察到数据源对
Map整体的赋值，以及调用Map的接口（如set、clear、delete）带来的变化。 - Set：可以观察到数据源对
Set整体的赋值，以及调用Set的接口（如add、clear、delete）带来的变化。
五、限制条件
@Param装饰器只能在@ComponentV2装饰器的自定义组件中使用。@Param装饰的变量表示组件外部输入，需要被初始化。支持使用本地初始值做初始化，当存在外部传入值时，将优先使用外部传入的值初始化，既不使用本地初始值，也不使用外部传入值是不允许的。@Param装饰的变量在子组件中无法进行修改（但对于对象类型变量，可修改其内部属性）。
六、使用场景
（一）从父组件到子组件变量传递与同步
@Param能够接受父组件@Local或@Param传递的数据并与之变化同步。例如：
@ObservedV2
class Region {@Trace x: number;@Trace y: number;constructor(x: number, y: number) {this.x = x;this.y = y;}
}
@ObservedV2
class Info {@Trace name: string;@Trace age: number;@Trace region: Region;constructor(name: string, age: number, x: number, y: number ) {this.name = name;this.age = age;this.region = new Region(x, y);}
}
@Entry
@ComponentV2
struct Index {@Local infoList: Info[] = [new Info("Alice", 8, 0, 0), new Info("Barry", 10, 1, 20), new Info("Cindy", 18, 24, 40)];build() {Column() {ForEach(this.infoList, (info: Info) => {MiddleComponent({ info: info })})Button("change").onClick(() => {this.infoList[0] = new Info("Atom", 40, 27, 90);this.infoList[1].name = "Bob";this.infoList[2].region = new Region(7, 9);})}}
}
@ComponentV2
struct MiddleComponent {@Require @Param info: Info;build() {Column() {Text(`name: ${this.info.name}`)Text(`age: ${this.info.age}`)SubComponent({ region: this.info.region })}}
}
@ComponentV2
struct SubComponent {@Require @Param region: Region;build() {Column() {Text(`region: ${this.region.x}-${this.region.y}`)}}
}
（二）装饰特定类型变量
- Date类型变量：可以观察到数据源对
Date整体的赋值，以及调用Date相关接口带来的变化。 - Map类型变量：可以观察到数据源对
Map整体的赋值，以及调用Map相关接口带来的变化。 - Set类型变量：可以观察到数据源对
Set整体的赋值，以及调用Set相关接口带来的变化。
（三）联合类型
@Param支持null、undefined以及联合类型。例如：
@Entry
@ComponentV2
struct Index {@Local count: number | undefined = 0;build() {Column() {// 相关操作及UI展示}}
}
综上所述，@Param装饰器在鸿蒙Next状态管理V2中为父子组件间的数据传递与同步提供了更方便的机制，开发者在使用时需注意其功能特点、变量传递规则、观察变化范围、限制条件以及不同类型变量的使用场景等，以便更好地在项目中应用该装饰器进行状态管理。
