鸿蒙Next状态管理V2 - @Param装饰器总结-原创手记-慕课网

一、概述

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