《从零到一:鸿蒙原生应用开发实战》第7篇:@State 装饰器入门——状态变,界面自动更新

你好，我是华鸿技术栈的作者。

上一篇我们手写了一个计数器组件，几行代码就搞定了点击按钮数字加一的功能。你回忆一下那个计数器，核心就靠一个东西撑着：@State count: number = 0。改 count 的值，界面跟着变，一行更新代码都没写。

这个 @State，就是 ArkUI 声明式 UI 的地基。

我带过不少从 Android、iOS 或者前端转过来的开发者，也跟一些做鸿蒙培训的同行聊过。发现一个规律：那些能快速上手 ArkUI 的人，不是基础多好，而是早早就把 @State 的运行逻辑吃透了。反过来，学了两个月还在各个组件之间绕弯的，基本都卡在状态管理这一块——数据变了 UI 不动，查半天不知道哪写错了，最后要么放弃，要么靠复制粘贴硬撑。

所以不少鸿蒙培训课程会把 @State 单独拉出来讲一整天，不是因为它难，是因为它太重要，后面 @Prop、@Link、@Provide 全部建立在它的基础上。今天这篇算是给你省了一天的培训费，咱们把 @State 的原理和用法拆透。

7.1 @State 到底干了什么

先看一段没有 @State 的代码，你马上就能感受到差别：

@Entry@Componentstruct NoStateDemo {  count: number = 0;  // 普通变量，没有 @State  build() {    Column() {      Text(`${this.count}`)        .fontSize(40)      Button('+1')        .onClick(() => {          this.count++;  // 值确实变了        })    }  }}

这段代码跑起来，你点按钮，count 的值确实在内存里加了，但屏幕上永远是 0。因为系统不知道 count 变了需要重新渲染界面。

加上 @State 之后：

@State count: number = 0;

点按钮，数字立刻更新。@State 的作用：把普通变量变成“响应式变量”。 变量值一变，用了这个变量的 UI 自动刷新，不用你手动调任何刷新方法。

两个核心规则：

1. @State 修饰的变量值发生变化时，ArkUI 会重新执行 build() 方法，更新用到这个变量的所有 UI 组件。

2. 只有当变量被“整体替换”（赋值新对象、新数组）或被 @Observed 配合追踪到内部属性变化时，框架才能感知到更新。直接修改对象内部的某个属性，框架不一定能感知到——这一点后面讲 @Observed 时会专门讲。

你现在可以理解为：@State 就是在告诉框架——“盯着这个变量，它一变，界面就要重画。”

7.2 @State 的两个规则，踩过一次就忘不了

规则一：变了就重画

这个已经演示过了，不再重复。再补充一个容易忽略的点：@State 变量的变化发生在异步回调里也一样生效，比如 setTimeout、网络请求的回调：

@State message: string = '加载中...';aboutToAppear(): void {  setTimeout(() => {    this.message = '加载完成';  // 异步修改，UI 也会刷新  }, 2000);}

规则二：同值不重画

ArkUI 在变量值变化时会做“同值检测”。如果新值和旧值相同，就算你写了赋值语句，UI 也不会重新渲染。框架这么做是为了避免不必要的刷新，节省性能：

@State count: number = 0;// 下面这行不会触发 UI 刷新，因为值没变this.count = 0;

这个规则在实际写代码时有个注意点：如果你频繁改变同一个值，比如动画里的帧更新，@State 本身是能正常响应的。框架做的是值比较，不是防抖。

7.3 实战：两个 @State 配合，做关注取关功能

计数器只用了单个 @State，实际页面往往有多个 @State 变量，它们之间互相独立，各管各的 UI。

下面做一个“粉丝关注”的卡片：显示博主名称、粉丝数，一个关注按钮，点了之后按钮文字和颜色都变，粉丝数自动增减。跑起来能看到，两个 @State 各自负责各自的状态，互不影响但能联合作战：

@Entry@Componentstruct FollowDemo {  @State followerCount: number = 1280;  @State isFollowed: boolean = false;  build() {    Column({ space: 20 }) {      // 博主名称      Text('华鸿技术栈')        .fontSize(24)        .fontWeight(FontWeight.Bold)      // 粉丝数——绑定 followerCount      Text(`粉丝：${this.followerCount}`)        .fontSize(16)        .fontColor('#666666')      // 关注按钮——文字和颜色绑定 isFollowed      Button(this.isFollowed ? '已关注' : '+ 关注')        .width(120)        .height(44)        .fontSize(16)        .backgroundColor(this.isFollowed ? '#CCCCCC' : '#007DFF')        .fontColor(Color.White)        .borderRadius(22)        .onClick(() => {          // 两个 @State 联动修改          this.isFollowed = !this.isFollowed;          if (this.isFollowed) {            this.followerCount++;  // 关注，粉丝+1          } else {            this.followerCount--;  // 取消关注，粉丝-1          }        })    }    .width('100%')    .height('100%')    .justifyContent(FlexAlign.Center)  }}

结论：多个 @State 变量的同步更新——一次点击同时修改了 isFollowed 和 followerCount，按钮样式和粉丝数同时刷新。ArkUI 会自动合并同一事件里的多次状态变更，只执行一次 build() 重绘，不会出现“先改按钮再改数字”这种闪烁。

这个“关注取关”模式你在后面写收藏、点赞、订阅功能时会反复用到。底层逻辑一模一样。

7.4 @State 能不能修饰对象和数组

计数器和关注按钮用的都是 number 和 boolean 这种基础类型。实际开发里数据通常是对象和数组——一篇文章有标题、作者、阅读量，一个列表里装着几十条数据。

@State 是支持修饰对象和数组的，但有一些行为需要记住。

对象：整体替换才能触发刷新

type Article = {  title: string;  readCount: number;};@State article: Article = {  title: '鸿蒙入门',  readCount: 100};// 这样做能触发 UI 刷新——整体替换this.article = {  title: '鸿蒙进阶',  readCount: 200};// 这样直接改内部属性，UI 可能不刷新this.article.readCount = 200;

直接修改 this.article.readCount 不触发刷新的原因，是 @State 追踪的是变量本身的引用变化，不会自动深入追踪对象内部属性的变化。需要通过整体替换对象来触发。

如果你想实现深层属性的响应式更新，需要配合 @Observed 和 @ObjectLink，这个在状态管理进阶篇里单独讲。现在先记住：@State 修饰对象时，整体替换对象才能可靠触发 UI 刷新。

数组：同理，整体替换

@State list: string[] = ['A', 'B', 'C'];// 这样做能触发 UI 刷新——整体替换this.list = ['A', 'B', 'C', 'D'];// push、pop 等方法修改数组，需要整体替换才能触发刷新const newList = [...this.list, 'D'];this.list = newList;

这里就是上一篇学的扩展运算符 ... 派上用场的地方——用扩展运算符生成一个新数组，再整体赋值给 @State 变量。这样既能修改数组内容，又能触发 UI 刷新。

7.5 @State 的常见踩坑点

坑一：直接改对象属性，UI 不刷新

@State user: { name: string } = { name: '张三' };// 这么写 UI 不刷新this.user.name = '李四';// 这么写 UI 刷新——整体替换this.user = { name: '李四' };

之所以不刷新，是因为 @State 追踪的是 user 这个变量引用的变化，不会深入追踪 user.name 这个子属性的变化。碰到需要深度追踪的场景，后面用 @Observed 和 @ObjectLink 解决。

坑二：数组用 push 直接改，UI 不刷新

@State items: string[] = ['A', 'B'];// push 不触发刷新this.items.push('C');// 用扩展运算符整体替换this.items = [...this.items, 'C'];

原因和对象一样——push 只是在原数组上加元素，引用地址没变。扩展运算符生成新数组，引用变了，框架能感知到。

坑三：init 里给 @State 赋值和在 aboutToAppear 里赋值的时机不同

aboutToAppear 是页面即将显示时的生命周期回调，在这之前 build() 已经执行过了。如果在 aboutToAppear 里修改 @State 变量，build() 会重新执行一次，界面上能看到最终结果。但这个行为有时会引发额外的重绘，后面讲生命周期时再专门说。

7.6 本篇总结

@State 的定位： 它是 ArkUI 状态管理的地基。后面要学的 @Prop、@Link、@Provide 都是在这个地基上延伸出来的。

三个核心规则：

适用场景：

• 组件内部的状态：计数器的数字、关注按钮的状态、输入框里的文字。

• 不需要跨组件共享的数据。如果需要父子组件共享数据，下一篇讲的 @Prop 和 @Link 会更合适。

关于 @State 的常见问题

Q: @State 和普通变量有什么区别？A: 普通变量改了不会触发 UI 刷新，屏幕上永远是旧值。@State 变量改了，用到这个变量的 UI 组件会自动重绘。

Q: @State 可以修饰对象吗？A: 可以，但直接改对象内部属性不会触发 UI 刷新。需要整体替换对象（比如 this.obj = { ...this.obj, key: newValue }），或者配合 @Observed 和 @ObjectLink 实现深度追踪。

Q: 数组用 push 修改，@State 能感知到吗？A: push 不会改变数组引用地址，@State 感知不到。用扩展运算符生成新数组再整体赋值：this.list = [...this.list, newItem]。

Q: 多个 @State 变量同时改了，UI 会刷新多次吗？A: 不会。同一事件里的多次状态变更，ArkUI 会自动合并，只执行一次 build()。

Q: 自学鸿蒙开发和参加鸿蒙培训，哪种方式更容易掌握状态管理？A: 无论哪种方式，状态管理都是核心难点。培训的优势在于有人帮你梳理逻辑链、及时纠正错误写法，省掉大量试错时间。自学的优势是灵活、成本低。如果选自学，跟着这个系列一篇篇敲下来，状态管理部分能覆盖到培训课程八成以上的内容。关键是每一篇的代码必须自己手敲一遍，光看是学不会的。

下一篇：关注按钮做出来了，但它现在只能在当前页面里用。下一篇我们把关注按钮拆成一个独立组件，再用 @Prop 和 @Link 把父子组件的数据打通——父组件传值给子组件，子组件改了父组件也能同步。组件封装和复用，就从下一篇开始。

本文由「华鸿技术栈」原创发布，专注鸿蒙原生应用与元服务开发。分享实战代码、源码解析、性能优化及生态前沿。不讲虚的，只上干货。转载请联系授权。