OpenHarmony父子组件单项同步使用：@Prop装饰器

最新推荐文章于 2025-12-09 16:18:17 发布

原创

最新推荐文章于 2025-12-09 16:18:17 发布 · 454 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#前端 #鸿蒙开发 #OpenHarmony #移动开发 #arkui #harmonyos

@Prop装饰的变量可以和父组件建立单向的同步关系。@Prop装饰的变量是可变的，但是变化不会同步回其父组件。

说明：

从API version 9开始，该装饰器支持在ArkTS卡片中使用。

概述

@Prop装饰的变量和父组件建立单向的同步关系：

● @Prop变量允许在本地修改，但修改后的变化不会同步回父组件。

● 当数据源更改时，@Prop装饰的变量都会更新，并且会覆盖本地所有更改。因此，数值的同步是父组件到子组件（所属组件)，子组件数值的变化不会同步到父组件。

装饰器使用规则说明

@Prop变量装饰器	说明
装饰器参数	无
同步类型	单向同步：对父组件状态变量值的修改，将同步给子组件@Prop装饰的变量，子组件@Prop变量的修改不会同步到父组件的状态变量上。嵌套类型的场景请参考观察变化。
允许装饰的变量类型	Object、class、string、number、boolean、enum类型，以及这些类型的数组。不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。支持Date类型。支持类型的场景请参考观察变化。必须指定类型。说明：不支持Length、ResourceStr、ResourceColor类型，Length，ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。在父组件中，传递给@Prop装饰的值不能为undefined或者null，反例如下所示。 CompA ({ aProp: undefined })； CompA ({ aProp: null }) @Prop和数据源类型需要相同，有以下三种情况： - @Prop装饰的变量和@State以及其他装饰器同步时双方的类型必须相同，示例请参考父组件@State到子组件@Prop简单数据类型同步。 - @Prop装饰的变量和@State以及其他装饰器装饰的数组的项同步时，@Prop的类型需要和@State装饰的数组的数组项相同，比如@Prop : T和@State : Array，示例请参考父组件@State数组中的项到子组件@Prop简单数据类型同步； - 当父组件状态变量为Object或者class时，@Prop装饰的变量和父组件状态变量的属性类型相同，示例请参考从父组件中的@State类对象属性到@Prop简单类型的同步。
嵌套传递层数	在组件复用场景，建议@Prop深度嵌套数据不要超过5层，嵌套太多会导致深拷贝占用的空间过大以及GarbageCollection(垃圾回收)，引起性能问题，此时更建议使用 @ObjectLink 。如果子组件的数据不想同步回父组件，建议采用@Reusable中的aboutToReuse，实现父组件向子组件传递数据，具体用例请参考组件复用场景。
被装饰变量的初始值	允许本地初始化。

变量的传递/访问规则说明

图1 初始化规则图示

观察变化和行为表现

观察变化

@Prop装饰的数据可以观察到以下变化。

● 当装饰的类型是允许的类型，即Object、class、string、number、boolean、enum类型都可以观察到赋值的变化。

// 简单类型
@Prop count: number;
// 赋值的变化可以被观察到
this.count = 1;
// 复杂类型
@Prop count: Model;
// 可以观察到赋值的变化
this.title = new Model('Hi');

当装饰的类型是Object或者class复杂类型时，可以观察到第一层的属性的变化，属性即Object.keys(observedObject)返回的所有属性；

class ClassA {
  public value: string;
  constructor(value: string) {
    this.value = value;
  }
}
class Model {
  public value: string;
  public a: ClassA;
  constructor(value: string, a: ClassA) {
    this.value = value;
    this.a = a;
  }
}
 
@Prop title: Model;
// 可以观察到第一层的变化
this.title.value = 'Hi'
// 观察不到第二层的变化
this.title.a.value = 'ArkUi'

对于嵌套场景，如果class是被@Observed装饰的，可以观察到class属性的变化，示例请参考 @Prop嵌套场景。

当装饰的类型是数组的时候，可以观察到数组本身的赋值、添加、删除和更新。

// @State装饰的对象为数组时
@Prop title: string[]
// 数组自身的赋值可以观察到
this.title = ['1']
// 数组项的赋值可以观察到
this.title[0] = '2'
// 删除数组项可以观察到
this.title.pop()
// 新增数组项可以观察到
this.title.push('3')

对于@State和@Prop的同步场景：

● 使用父组件中@State变量的值初始化子组件中的@Prop变量。当@State变量变化时，该变量值也会同步更新至@Prop变量。

● @Prop装饰的变量的修改不会影响其数据源@State装饰变量的值。

● 除了@State，数据源也可以用@Link或@Prop装饰，对@Prop的同步机制是相同的。

● 数据源和@Prop变量的类型需要相同，@Pro