鸿蒙 ArkUI 状态管理｜@State 装饰器完整详解 + 实战模拟案例

前言

在 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装饰器。