鸿蒙应用开发之父子组件传参：@Prop 装饰器使用教程

这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 Github，点击此处查看项目。欢迎大家交流、指正，也欢迎提交 PR。

一、引言

在鸿蒙 ArkUI 框架中，状态管理是构建动态交互界面的核心。@Prop 装饰器是实现父子组件间单向数据同步的关键工具。它允许父组件将状态值传递给子组件，子组件可以读取并临时修改该值，但修改不会影响父组件。当父组件的状态更新时，会强制覆盖子组件的本地修改。

本文将深入讲解 @Prop 的工作原理、使用场景，并通过完整示例帮助你快速掌握。

二、@Prop 核心特性

@Prop 的设计遵循单向数据流原则，其核心特性如下：

数据流向：单向（父 ➔ 子）。父组件是唯一的数据源。
类型支持 ：string、number、boolean、enum、Date、Map、Set，以及这些类型的数组或 Object/class。
本地修改 ：子组件可修改 @Prop 变量，但修改仅限组件内部，不会回传给父组件。
父组件覆盖：父组件状态变化时，会强制覆盖子组件的本地修改，确保数据一致性。

三、完整示例：计数器应用

以下示例展示如何在鸿蒙中实现父组件向子组件单向传递数据，并说明子组件内部修改 @Prop 后会被父组件覆盖的特性。

3.1 子组件定义

typescript 复制代码

@Component
struct ChildComponent {
  // 接收父组件传递的 count 值
  @Prop count: number;

  build() {
    Column() {
      Text(`子组件接收到的 count: ${this.count}`)
        .fontSize(20)
        .margin(10)

      Button('子组件本地 +1（不通知父组件）')
        .onClick(() => {
          // 修改 @Prop 变量：仅在本组件内生效
          this.count += 1;
          console.log(`子组件内 count 改为 ${this.count}`);
        })
    }
    .padding(10)
    .backgroundColor('#E0E0E0')
    .borderRadius(10)
  }
}

3.2 父组件定义

typescript 复制代码

@Entry
@Component
struct ParentComponent {
  @State parentCount: number = 0;

  build() {
    Column() {
      Text(`父组件 count: ${this.parentCount}`)
        .fontSize(24)
        .margin(10)

      Button('增加父组件 count')
        .onClick(() => {
          this.parentCount += 1;
        })

      // 传递数据给子组件
      ChildComponent({ count: this.parentCount })
        .margin({ top: 20 })

      // 演示父组件覆盖子组件的本地修改
      Button('强制刷新父组件（覆盖子组件本地修改）')
        .onClick(() => {
          this.parentCount++; // 触发父组件状态更新
        })
    }
    .padding(20)
    .width('100%')
    .height('100%')
  }
}

运行效果：

四、运行效果说明

初始状态 ：父子组件的 count 均为 0。
点击"子组件本地 +1" ：
- 子组件内部 this.count 变为 1，页面显示 "子组件接收到的 count: 1"。
- 父组件的 parentCount 仍为 0，不受影响。
点击"增加父组件 count" ：
- 父组件 @State 更新，parentCount 变为 1。
- 子组件的 @Prop 被父组件覆盖，立即重新显示为 1（即使子组件之前已修改为其他值）。
点击"强制刷新父组件" ：
- 即使子组件本地修改过，父组件状态更新后，子组件显示的值会强制同步为父组件的最新值。

五、关键要点与最佳实践

单向性 ：@Prop 是只读的（从父组件角度看），子组件不能通过修改 @Prop 来更新父组件。
数据同步 ：父组件 @State 变化时，子组件 @Prop 会立即更新，且覆盖子组件的本地改动。
修改范围 ：子组件内部可以更改 @Prop 变量，但这种修改是临时的、局部的，不会影响父组件或其他子组件。
适用场景：这种模式适合需要父组件控制数据源、子组件仅做展示或临时交互的场景，例如表单的预览组件、配置项展示卡片等。

六、总结

@Prop 是鸿蒙应用开发中实现单向数据流的简洁方案。通过本文的示例，你应该已经掌握了它的基本用法和核心特性。在实际开发中，合理使用 @Prop 可以帮你构建更清晰、可维护的组件树。

当数据结构包含多层嵌套（如对象中包含对象、数组等），且需要监听深层属性的变化时，使用 @Observed + @ObjectLink 组合是最佳实践。