一、概述
为增强子组件接受外部参数输入的能力，开发者可使用@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中为父子组件间的数据传递与同步提供了更方便的机制，开发者在使用时需注意其功能特点、变量传递规则、观察变化范围、限制条件以及不同类型变量的使用场景等，以便更好地在项目中应用该装饰器进行状态管理。
SOCIAL SHARE CARD GENERATOR