程序员Feri  | 13年编程老炮，拆解技术脉络，记录程序员的进化史

Hello，我是Feri。

在HarmonyOS的声明式UI框架中，UI是数据状态的“实时投影” ——就像投影仪的画面由胶片决定，UI界面的展示效果由“状态数据”控制。当状态数据变化时，UI会自动同步刷新；如果数据没有被特殊标记，UI只能保持初始化时的样子，后续再改数据也不会有任何反应。

这篇文章将用“通俗类比+实操示例”的方式，拆解HarmonyOS 6.0中最核心的3个组件内状态装饰器（@State、@Prop、@Link），帮你彻底搞懂“数据怎么驱动UI”，以及父子组件间如何传递状态。

一、先搞懂：状态管理的核心概念（3分钟入门）

在开始写代码前，先理清几个关键概念，避免后续踩坑：

核心逻辑一句话总结：只有被装饰器标记的“状态变量”，才能驱动UI刷新；常规变量再改，UI也“视而不见”。

二、组件内状态装饰器：3个核心装饰器的用法与区别

状态装饰器的核心作用是“标记数据”，告诉框架：“这个数据要和UI绑定，变了就刷新界面”。下面逐个拆解最常用的3个装饰器，每个都配“类比+示例+效果”，一看就懂。

1. @State：组件内部的“私有状态开关”

核心作用：控制当前组件的UI刷新（数据只在自己组件内生效）

@State就像你房间里的“台灯开关”——只能控制自己房间的灯，开关状态变了，只有你房间的灯亮灭变化，不影响其他房间。

适用场景：

• 数据只在当前组件内使用，不需要传给其他组件（比如组件内的按钮点击次数、输入框内容）；
• 变量会直接出现在UI上（比如Text显示的文字、Button的点击次数）。

语法规则：

// 必须指定类型+本地初始化（不能只声明不赋值）@State 变量名: 数据类型 = 初始值;

实操示例：状态变量vs常规变量的区别

下面的代码对比了“状态变量”和“常规变量”的差异，点击按钮就能看到效果：

@Entry
@Component
struct StateDemo {
  // 状态变量：被@State标记，改了UI会刷新
  @State clickCount: number = 0;
  // 常规变量：没被标记，改了UI无反应
  normalCount: number = 0;

  // 状态变量支持基本类型（string/number）和引用类型（数组/对象）
  @State inputText: string = ""; // 基本类型
  @State numList: number[] = []; // 引用类型

  build() {
    Column({ space: 20 }) {
      // 1. 状态变量：点击按钮→count变→UI刷新
      Button(`状态变量-点击次数：${this.clickCount}`)
        .onClick(() => this.clickCount++) // 改状态变量
        .backgroundColor("#007AFF")

      // 2. 常规变量：点击按钮→count变→UI不刷新
      Button(`常规变量-点击次数：${this.normalCount}`)
        .onClick(() => {
          this.normalCount++;
          console.log("常规变量实际值：", this.normalCount); // 控制台能看到变，但UI不变
        })
        .backgroundColor("#666666")

      // 3. 状态变量（基本类型）：输入框内容同步到Text
      TextInput({ placeholder: "请输入文字" })
        .onChange((value) => this.inputText = value) // 输入框内容→状态变量
        .width("90%")
        .border({ width: 1, color: "#EEEEEE" })

      Text(`你输入的内容：${this.inputText}`)
        .fontSize(20)
        .fontColor(Color.Red)

      // 4. 状态变量（引用类型）：数组新增元素→List自动刷新
      Button("给数组加一个随机数")
        .onClick(() => {
          this.numList.push(Math.floor(Math.random() * 100)); // 数组新增元素
        })
        .backgroundColor("#34C759")

      List({ space: 10 }) {
        ForEach(this.numList, (num: number) => {
          ListItem() {
            Text(`数组元素：${num}`)
              .width("100%")
              .padding(15)
              .backgroundColor("#F5F5F5")
          }
        })
      }
    }
    .width("100%")
    .height("100%")
    .padding(20)
  }
}

效果解析：

• 点击第一个按钮：clickCount（状态变量）变了→按钮文字实时更新；
• 点击第二个按钮：normalCount（常规变量）变了→按钮文字不变，但控制台能看到数值变化；
• 输入框打字：inputText（状态变量）变了→下方Text实时显示输入内容；
• 点击第四个按钮：数组numList（状态变量）新增元素→List自动新增一行。

关键注意点：

• @State变量是组件“私有”的，只能在当前组件内访问，子组件不能直接用；
• 必须本地初始化（比如@State num: number = 0，不能只写@State num: number）；
• 支持基本类型（string/number/boolean）和引用类型（array/object），引用类型只要内部元素变了（比如数组push），也会触发UI刷新。

2. @Prop：父子组件的“单向数据通道”（父传子，子改不回传）

核心作用：父组件给子组件传状态，子组件能改但不影响父组件

@Prop就像父母给孩子的“零花钱”——父母（父组件）给多少，孩子（子组件）就有多少；孩子可以自己花（本地修改），但花完不会让父母的钱包自动变少（不回传父组件）；如果父母再给一笔零花钱（父组件数据变了），会覆盖孩子手里剩下的钱（子组件本地修改被覆盖）。

适用场景：

• 父组件需要给子组件传递初始数据；
• 子组件可以修改数据，但不需要同步回父组件（比如子组件内的临时状态）。

语法规则：

// 子组件中使用：必须指定类型+本地初始化（父组件传值会覆盖默认值）@Prop 变量名: 数据类型 = 初始值;

实操示例：父组件输入，子组件显示

步骤1：创建子组件（接收父组件数据）

// ChildProp.ets（子组件）
@Component
export struct ChildProp {
  // @Prop修饰：接收父组件传递的字符串，默认值为"默认标题"
  @Prop title: string = "默认标题";

  build() {
    Row({ space: 15 }) {
      Image($r("app.media.startIcon")) // 本地资源图片（需自行添加）
        .width(80)
        .height(80)
      Text(this.title)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
    }
    .width("90%")
    .padding(15)
    .border({ width: 1, color: "#EEEEEE", radius: 10 })
  }
}

步骤2：父组件使用子组件（传递数据）

// PropDemo.ets（父组件/页面）
import { ChildProp } from '../components/ChildProp';

@Entry
@Component
struct PropDemo {
  // 父组件的状态变量：作为子组件的数据源
  @State parentTitle: string = "";

  build() {
    Column({ space: 30 }) {
      // 输入框：修改父组件的状态变量
      TextInput({ placeholder: "请输入子组件要显示的标题" })
        .onChange((value) => this.parentTitle = value)
        .width("90%")
        .border({ width: 1, color: "#EEEEEE" })
        .padding(10)

      // 子组件：通过命名参数传递数据（父→子）
      ChildProp({ title: this.parentTitle })
    }
    .width("100%")
    .height("100%")
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

效果解析：

• 父组件输入框打字→parentTitle变→子组件的title同步变→子组件Text刷新；
• 如果子组件内修改this.title（比如加个按钮onClick(() => this.title = "子组件修改")）： 子组件的Text会暂时显示“子组件修改”；但父组件的parentTitle不变，一旦父组件再输入文字（parentTitle变），子组件的title会被父组件的新值覆盖。

关键注意点：

• 单向同步：父变→子变，子变→父不变；
• 子组件的@Prop变量必须本地初始化（默认值），父组件传值时会覆盖默认值；
• 支持的类型：基本类型（string/number/boolean），不支持引用类型（array/object）。

3. @Link：父子组件的“双向数据通道”（父传子，子改父也变）

核心作用：父子组件共享同一状态，一方修改，双方同步刷新

@Link就像夫妻共用的“银行卡”——丈夫（父组件）存钱、妻子（子组件）花钱，账户余额会实时同步；不管哪一方操作，双方看到的余额都是最新的。

适用场景：

• 父子组件需要共同操作同一数据（比如购物车数量、开关状态）；
• 子组件的修改需要同步回父组件，确保数据一致。

语法规则：

// 子组件中使用：必须指定类型，绝对不能本地初始化（只能靠父组件传值）@Link 变量名: 数据类型;

实操示例：父子组件共同修改一个数值

步骤1：创建子组件（通过@Link绑定父组件数据）

// ChildLink.ets（子组件）
@Component
export struct ChildLink {
  // @Link修饰：绑定父组件的状态变量，无默认值
  @Link count: number;

  build() {
    Column({ space: 15 }) {
      Text(`子组件：当前数值 = ${this.count}`)
        .fontSize(25)
        .fontColor(Color.Red)

      // 子组件修改数值：会同步回父组件
      Button("子组件-数值减2")
        .onClick(() => this.count -= 2)
        .backgroundColor("#FF3B30")
        .width("80%")
    }
    .width("90%")
    .padding(20)
    .border({ width: 1, color: Color.Red, radius: 10 })
  }
}

步骤2：父组件使用子组件（传递状态变量）

// LinkDemo.ets（父组件/页面）
import { ChildLink } from '../components/ChildLink';

@Entry
@Component
struct LinkDemo {
  // 父组件的状态变量：作为子组件的共享数据源
  @State parentCount: number = 0;

  build() {
    Column({ space: 30 }) {
      // 父组件显示数值
      Text(`父组件：当前数值 = ${this.parentCount}`)
        .fontSize(25)
        .fontWeight(FontWeight.Bold)

      // 父组件修改数值：会同步到子组件
      Button("父组件-数值加2")
        .onClick(() => this.parentCount += 2)
        .backgroundColor("#007AFF")
        .width("80%")

      // 子组件：通过命名参数传递@Link变量（必须传，不能漏）
      ChildLink({ count: this.parentCount })
    }
    .width("100%")
    .height("100%")
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

效果解析：

• 点击父组件的“加2”按钮→parentCount变→父子组件的Text同时显示新数值；
• 点击子组件的“减2”按钮→count变→父子组件的Text同时显示新数值；
• 父子组件操作的是“同一笔数据”，双方状态完全同步。

关键注意点：

• 双向同步：父变→子变，子变→父变；
• 子组件的@Link变量绝对不能本地初始化（比如不能写@Link count: number = 0），必须由父组件传递；
• 支持的类型：基本类型（string/number/boolean）和引用类型（array/object），引用类型的修改会双向同步；
• 传值时必须直接传递“状态变量”（比如ChildLink({ count: this.parentCount })），不能传递普通变量或表达式。

三、3个装饰器核心区别对比（避坑关键）

通俗总结：

• 只在自己组件用→用@State；
• 父给子传数据，子改了不用告诉父→用@Prop；
• 父和子要一起改同一个数据→用@Link。

四、实操练习（巩固知识点）

1. 基础练习：用@State实现一个“计数器”，点击按钮加1，同时显示当前计数，再加一个“重置”按钮清空计数；
2. 单向传递练习：父组件有一个开关（boolean类型状态变量），通过@Prop传给子组件，子组件根据开关状态显示“开启”或“关闭”文本；
3. 双向传递练习：父组件有一个输入框，子组件也有一个输入框，通过@Link实现“两个输入框内容实时同步”（改一个，另一个自动变）。

按照上面的示例代码，动手写一遍就能彻底掌握——状态管理的核心就是“标记变量→绑定UI→传递数据”，多练两次就能形成肌肉记忆啦！

五、总结

HarmonyOS 6.0 声明式 UI 的状态管理，核心是 “用装饰器标记状态变量，让数据驱动 UI 自动刷新” —— 无需手动操作 DOM，只需关注数据变化，框架就会帮我们同步更新界面，这也是声明式开发高效简洁的关键。

三个核心装饰器的定位的使用场景可以一句话概括：

1. @State：组件内的 “私有驱动”，数据只在当前组件生效，适合控制自身 UI（如按钮点击次数、输入框内容）；
2. @Prop：父子间的 “单向通道”，父组件传值给子组件，子组件可本地修改但不回传，适合子组件临时使用父数据的场景；
3. @Link：父子间的 “双向桥梁”，数据由父子共享，一方修改双方同步，适合需要共同操作同一数据的场景。 关键避坑原则：

• 只有被装饰器标记的 “状态变量” 能驱动 UI，常规变量修改无效；
• @State 和 @Prop 需本地初始化，@Link 绝对不能手动赋值，必须由父组件传递；
• 数据流向决定装饰器选择：组件内用 @State、单向传用 @Prop、双向共用用 @Link。

掌握这三个装饰器，就能轻松解决大多数 UI 与数据联动的需求，让声明式开发的逻辑更清晰、代码更简洁，完美适配 HarmonyOS 的开发范式。