HarmonyOS 6.0应用开发——V2装饰器@param的使用

【高心星出品】

文章目录

• • • V2装饰器@param的使用
    • • 概念
      • 使用方法
      • 案例

V2装饰器@param的使用

概念

在鸿蒙ArkTS开发中，@Param装饰器是组件间状态管理的重要工具，主要用于父子组件间的单向数据传递，这一点与V1中的@prop类似。

• @Param装饰的变量支持本地初始化，但不允许在组件内部直接修改。
• 被@Param装饰的变量能够在初始化自定义组件时从外部传入，当数据源也是状态变量时，数据源的修改会同步给@Param。
• @Param可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等。
• @Param装饰的变量变化时，会刷新该变量关联的组件。
• @Param支持对基本类型（如number、boolean、string、Object、class）、内嵌类型（如Array、Set、Map、Date），以及null、undefined和联合类型进行观测。
• 对于复杂类型如类对象，@Param会接受数据源的引用。在组件内可以修改类对象中的属性，该修改会同步到数据源。
• @Param的观测能力仅限于被装饰的变量本身。详见观察变化。

使用方法

1. 数据流向
   单向同步（父组件 → 子组件），仅支持父组件数据源变化触发子组件更新。
2. 适用条件 1
   • 仅限@ComponentV2装饰的组件（API version 12+）。
   • 子组件禁止直接修改@Param装饰的变量（需通过@Once或事件触发父组件修改）。
3. 支持类型
   基本类型（number/boolean/string等）、对象、数组、Date/Map/Set等内嵌类型，以及null/undefined和联合类型。

@Param变量装饰器	说明
装饰器参数	无。
能否本地修改	否。若需要修改值，可使用@Param搭配@Once修改子组件的本地值。或通过@Event装饰器，修改@Param数据源的值。
同步类型	由父到子单向同步。
允许装饰的变量类型	Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。
被装饰变量的初始值	允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。

传递规则	说明
从父组件初始化	@Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。当同时存在本地初始值与外部传入值时，优先使用外部传入值进行初始化。
初始化子组件	@Param装饰的变量可以初始化子组件中@Param装饰的变量。
同步	@Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。

案例

子组件中有一个按钮展示@param装饰的count，但是不能更新本地的count，父组件中有一个按钮展示@local装饰的count，并且与子组件的count绑定，形成单向通信效果。点击父组件按钮会更新父子两者的组件显示数据。@require配合@param会强制要求父组件初始化子组件数据。

@ComponentV2
struct child {
  // 强制父组件传参
  @Require @Param count:number
  // 父组件可以传参也可以不传参
  // @Param count: number = 10

  build() {
    Column() {
      Button('child count: ' + this.count)
        .width('60%')
        .onClick(() => {
          // 这里会报错，因为@param装饰的数据不能自己更新，需要让父组件更新 同步进来
          // this.count+=1
        })
    }
    .width('100%')
    .padding(20)
  }
}

@Entry
@ComponentV2
struct Parampage {
  @Local count: number = 10;
  build() {
    Column({ space: 20 }) {
      Button('page count: ' + this.count)
        .width('60%')
        .onClick(() => {
          this.count += 1
        })
      // child count与 父组件count单向绑定
      child({ count: this.count })
    }
    .height('100%')
    .width('100%')
  }
}

同步数据为数组的时候，子组件中可以修改数组元素，不能初始化整个数组，这里的修改会形成双向同步关系，下面案例里面点击两个按钮数据会同时变化。

@ComponentV2
struct child2 {
  @Require @Param arr:number[]

  build() {
    Column() {
      Button('child count: ' + this.arr[0])
        .width('60%')
        .onClick(() => {
          // 不可以修改整个数组，但是可以修改数组元素 形成双向同步
          this.arr[0]+=1
        })
    }
    .width('100%')
    .padding(20)
  }
}

@Entry
@ComponentV2
struct Parampage1 {
  @Local arr:number[]=[1,2,3]
  build() {
    Column({ space: 20 }) {
      Button('page count: ' + this.arr[0])
        .width('60%')
        .onClick(() => {
          this.arr[0]+=1
        })
      // child arr与 父组件arr单向绑定
      child2({arr:this.arr })
    }
    .height('100%')
    .width('100%')
  }
}

如果单向同步的数据是复杂的结构info类，在子组件中@param装饰的数据可以进行修改其属性并且会同步给父组件形成局部双向通信，

在下面案例中点击子组件按钮的时候in的count值已经发生了修改，父组件中的count也会修改，只不过@param和@local没有观察到，当先点击子组件按钮再点击父组件按钮的时候就会观察到两者显示10--12--14 .

class info{
  count:number
  constructor(count:number) {
    this.count=count
  }
}

@ComponentV2
struct child2 {
  @Require @Param in:info=new info(10)

  build() {
    Column() {
      Button('child count: ' + this.in.count)
        .width('60%')
        .onClick(() => {
          // param不允许本地修改
          // this.in=new info(11)
          // 允许修改对象的属性 并且会同步到父组件 形成有限制的双向同步
          this.in.count+=1
        })
    }
    .width('100%')
    .padding(20)
  }
}

@Entry
@ComponentV2
struct Parampage1 {
  @Local in:info=new info(10)
  build() {
    Column({ space: 20 }) {
      Button('page count: ' + this.in.count)
        .width('60%')
        .onClick(() => {
          this.in=new info(this.in.count+1)
        })
      // child count与 父组件count单向绑定
      child2({ in: this.in })
    }
    .height('100%')
    .width('100%')
  }
}