鸿蒙 Next 中 Prop 的用法详解

一、@Prop概述

在鸿蒙Next中，@Prop装饰器用于在父子组件之间建立单向的数据同步关系。这意味着数据从父组件流向子组件，子组件对@Prop装饰变量的修改不会同步回父组件。从API version 9开始，该装饰器支持在ArkTS卡片中使用，从API version 11开始，支持在元服务中使用。

（一）同步机制

1. 父组件状态变量值的修改会同步给子组件@Prop装饰的变量。
2. 子组件@Prop变量的修改不会影响父组件的状态变量。
3. 当数据源（如父组件中的@State变量）更改时，@Prop装饰的变量会更新，并且会覆盖本地对该变量的所有更改。

（二）限制条件

1. @Prop装饰变量时会进行深拷贝，除基本类型、Map、Set、Date、Array外，其他类型在拷贝过程中可能丢失类型信息。
2. 不能在@Entry装饰的自定义组件中使用@Prop装饰器。

二、装饰器使用规则

1. 参数：无参数。
2. 同步类型：单向同步。

3. 允许装饰的变量类型

   • Object、class、string、number、boolean、enum类型及其数组。
   • 支持Date类型。
   • API11及以上支持Map、Set类型。
   • 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。

   • 必须指定类型，且@Prop和数据源类型需相同，有以下三种情况：

     • @Prop装饰的变量和@State以及其他装饰器同步时双方类型必须相同。
     • @Prop装饰的变量和@State以及其他装饰器装饰的数组的项同步时，@Prop的类型需要和@State装饰的数组的数组项相同。
     • 当父组件状态变量为Object或者class时，@Prop装饰的变量和父组件状态变量的属性类型相同。
   • API11及以上支持上述支持类型的联合类型，如string | number、string | undefined或ClassA | null。
4. 嵌套传递层数：在组件复用场景，建议@Prop深度嵌套数据不要超过5层，以免因深拷贝占用过多空间和导致垃圾回收问题影响性能，此时可考虑使用@ObjectLink。
5. 被装饰变量的初始值：允许本地初始化；若在API 11中和@Require结合使用，则必须父组件构造传参。

三、变量的传递/访问规则

1. 从父组件初始化

   • 若本地有初始化，则为可选；否则必选。支持父组件中的常规变量（仅初始化数值，变化不触发UI刷新，只有状态变量能触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp去初始化子组件中的@Prop变量。
2. 用于初始化子组件：@Prop支持去初始化子组件中的常规变量、@State、@Link、@Prop、@Provide。
3. 是否支持组件外访问：@Prop装饰的变量是私有的，只能在组件内访问。

四、观察变化和行为表现

（一）观察变化

1. 简单类型：如number、string、boolean等，可观察到赋值的变化。

2. 复杂类型（Object或class）

   • 可以观察到第一层属性的赋值变化。
   • 若class被@Observed装饰，可观察到class属性的变化（嵌套场景）。
3. 数组类型：可观察到数组本身的赋值和数组项的添加、删除和更新。
4. Date类型：可观察到Date整体的赋值，以及通过其接口更新属性的操作。
5. Map类型（API11及以上）：可观察到Map整体的赋值和通过其接口更新值的操作。
6. Set类型（API11及以上）：可观察到Set整体的赋值和通过其接口更新值的操作。

（二）框架行为

1. 初始渲染

   • 执行父组件的build()函数创建子组件实例并传递数据源。
   • 初始化子组件@Prop装饰的变量。

2. 更新

   • 子组件@Prop更新时，仅在当前子组件内，不会同步回父组件。
   • 父组件数据源更新时，子组件@Prop变量被重置，本地修改被覆盖。
   • 注意：@Prop装饰的数据更新依赖所属自定义组件的重新渲染，应用进入后台后无法刷新，推荐使用@Link代替。

五、使用场景示例

（一）父组件@State到子组件@Prop简单数据类型同步

父组件ParentComponent的@State变量countDownStartValue初始化子组件CountDownComponent的@Prop变量count。点击父组件按钮修改countDownStartValue会同步更新子组件count，而子组件修改count不会影响父组件。

（二）父组件@State数组项到子组件@Prop简单数据类型同步

父组件Index的@State数组arr的数组项初始化子组件Child的@Prop变量value。子组件修改value不会同步回父组件，父组件修改arr会更新相应子组件的value。

（三）从父组件中的@State类对象属性到@Prop简单类型的同步

父组件Library的@State图书对象book初始化子组件ReaderComp的@Prop变量book。子组件对book的本地更改（如标记为已读）不会同步给父组件。

（四）从父组件中的@State数组项到@Prop class类型的同步

父组件Library的@State数组allBooks包含Book对象，子组件ReaderComp的@Prop变量book接收数组项。需使用@Observed装饰Book类，否则无法观察到Book对象属性的更改（如标记为已读），且子组件@Prop变量的修改不会同步给父组件。

（五）@Prop本地初始化不和父组件同步

子组件MyComponent有两个@Prop变量，customCounter无本地初始化，需父组件提供数据源；customCounter2有本地初始化，父组件可选择是否同步数据源，且父组件初始化的值会覆盖子组件本地初始化的值。

（六）@Prop嵌套场景

在嵌套场景下，每一层类都要用@Observed装饰，且每一层都要被@Prop接收，才能观察到嵌套场景中的数据变化。例如，父组件Parent的@State变量votes（类型为ClassB，包含ClassA对象），通过@Prop传递给子组件Child1，并在多层嵌套结构中实现数据的单向同步和观察。

六、常见问题

1. @Prop装饰状态变量未初始化错误：确保@Prop装饰的变量在合适的时机进行初始化。
2. 使用a.b(this.object)形式调用，不会触发UI刷新：注意只有状态变量的变化才能触发UI刷新，常规变量赋值给@Prop仅初始化数值，其变化不触发UI刷新。