前言

在 HarmonyOS ArkTS 声明式 UI 开发中，数据驱动视图是核心设计思想。页面不会手动操作 DOM 刷新，而是通过状态变量自动更新界面。
@State 是所有状态装饰器里最基础、使用频率最高的装饰器，用于定义组件内部私有响应式状态，也是学习其他状态装饰器（@Prop/@Link/@Observed）的前置知识。
现在给大家完整讲解@State原理、使用规范、三套可直接运行的模拟 Demo。

一、@State 装饰器基础概述

1. 核心定义
被@State修饰的变量称为状态变量，普通变量仅存储数据，页面无法感知变更；而状态变量会和绑定的 UI 组件建立响应式关联：
当状态变量的值发生修改时，框架会自动刷新所有依赖该变量的页面组件，无需手动重绘页面。
2. 官方版本支持
API Version 9：支持在 ArkTS 卡片中使用@State
API Version 11：拓展支持元服务场景使用
3. 定位
@State仅管理当前自定义组件内部的独立状态，是组件私有数据源，无法直接跨组件共享数据（跨组件传值需要搭配@Prop/@Link）。

二、核心原理：普通变量 vs @State 状态变量

简单理解：@State给变量加了一层「数据监听」，一旦数值变动，立刻通知页面更新视图。

三、@State 强制使用规范（避坑要点）
声明位置限制
1.只能写在struct自定义组件内部，不能在全局、函数内定义；
必须初始化赋值
2.不允许仅声明变量，必须赋予初始值：

// 正确 @State flag:boolean = true

// 错误 @State flag:boolean

3.支持的数据类型
基础类型（string/number/boolean）、自定义 Class 对象、数组Array；
4.私有作用域
状态仅当前组件可用，父 / 子组件无法直接读取修改；
5.触发刷新条件
直接对变量整体赋值才会触发页面更新，仅修改对象内部属性时，复杂对象需搭配@Observed。

四、三套实战模拟代码（课堂完整案例）
案例 1：布尔状态切换（文字 + 颜色动态变更）
需求：点击按钮切换布尔值，同步修改页面文字、文字颜色，直观感受响应式刷新

@Entry
@Component
struct StateBoolDemo{
  // 响应式布尔状态变量
  @State isShow:boolean = true
  // 普通变量（修改不会刷新页面，仅作对比）
  private num:number = 1
  build() {
    Column({space:60}){
      // 三元表达式绑定状态，文字、颜色随isShow同步变化
      Text(this.isShow?"状态已开启":"状态已关闭")
        .fontSize(36)
        .fontWeight(FontWeight.Bold)
        .fontColor(this.isShow?Color.Red:Color.Yellow)
      
      Button("点击切换状态")
        .width('100%')
        .height(50)
        .fontSize(24)
        .backgroundColor(0x007dff)
        // 点击取反布尔值，页面自动刷新Text
        .onClick(()=>{
          this.isShow = !this.isShow
        })
    }
    .width('100%')
    .height('100%')
    .padding(30)
  }
}

效果说明：点击按钮后isShow值翻转，上方文本内容、字体颜色同时自动切换，无任何手动刷新代码。

案例 2：数字计数器（加减按钮实时更新数值）
需求：两个按钮分别实现数字自增、自减，顶部文本实时展示当前数字

@Entry
@Component
struct StateNumDemo{
  // 数字类型响应式状态
  @State num:number = 0
  build() {
    Column({space:30}){
      Text(`当前的数是：${this.num}`)
        .fontSize(35)
        .fontWeight(FontWeight.Bolder)
      
      Row({space:20}){
        Button("- 递减")
          .width('47%')
          .height(50)
          .fontSize(26)
          .onClick(()=>{
            this.num--
          })
        Button("+ 递加")
          .width('47%')
          .height(50)
          .fontSize(26)
          .onClick(()=>{
            this.num++
          })
      }
    }
    .width('100%')
  }
}

四、总结

1.@State是 ArkUI 响应式开发的入门核心，完美体现数据驱动视图；
2.仅用于组件内部私有状态，跨组件数据共享需要学习@Prop/@Link；
3.和普通私有变量最大区别：变量修改后自动刷新关联 UI 组件；
4.开发表单、计数器、开关类页面优先使用@State，代码简洁、无需手动操作界面。

拓展学习：当状态需要在父子组件传递、多组件共享时，可查阅官方文档学习@Link、@Prop、@ObservedObject装饰器。