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

程序员黑黑

44人浏览 · 2026-07-02 09:45:00

程序员黑黑 · 2026-07-02 09:45:00 发布

文章目录

一、引言

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

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

二、@Prop 核心特性

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

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

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

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

3.1 子组件定义

@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 父组件定义

@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（即使子组件之前已修改为其他值）。
点击“强制刷新父组件”：
- 即使子组件本地修改过，父组件状态更新后，子组件显示的值会强制同步为父组件的最新值。