菜鸟-创作你的创作

鸿蒙中@State的原理使用详解(HarmonyOS 5)

lichongyang

3 月前

下面给你整理一份 《HarmonyOS 5 @State 原理与使用详解》，包含概念、工作原理、使用方法以及最佳实践，适合前端开发者在 AbilitySlice / Composable 场景中快速掌握状态管理。

HarmonyOS 5 @State 原理与使用详解

在 HarmonyOS 5（基于 ArkUI 框架）中，@State 是最核心的状态管理注解，用于响应式 UI 更新。理解它的原理，有助于高效编写可维护的页面。

一、@State 基本概念

定义：@State 用于标记 可变的、会触发 UI 更新的属性
作用：当标记的变量改变时，框架会自动 重新渲染相关 Composable 组件
适用场景：UI 页面中的按钮状态、输入框内容、列表数据等

示例：

@State
var counter = 0

二、@State 工作原理

HarmonyOS 5 的 @State 背后是 响应式数据机制，原理如下：

数据劫持
- @State 标记的变量在编译时被包装成 可观察对象
- 内部会拦截 get/set 方法
依赖收集
- 当 Composable 使用该变量时，会记录该组件对变量的依赖关系
- 例如：Text(counter.toString()) 会订阅 counter
状态变更触发
- 变量赋值时，会触发依赖收集的组件重新执行渲染逻辑
- 类似 Jetpack Compose 的 StateFlow / SwiftUI 的 @State
增量渲染
- HarmonyOS 只会更新受影响的组件，而不是整个界面
- 提高性能

图示：

@State variable  --->  Composable component
       set()         |依赖|
      notify UI ---> re-render

三、@State 使用方法

1. 定义状态变量

@State
var username: String = ""
@State
var isLogin: Boolean = false

变量可以是基本类型，也可以是集合
集合类型推荐使用 mutableListOf() / mutableMapOf()，否则无法触发 UI 更新

2. 在 Composable 中使用

Column() {
    Text("Welcome, $username")
    Button("Login") {
        isLogin = true
        username = "HarmonyOSUser"
    }
    if (isLogin) {
        Text("Login successful")
    }
}

当 isLogin 或 username 改变时，对应的 Text 会自动刷新
无需手动调用 invalidate() 或 notifyDataSetChanged()

3. 集合类型状态

@State
var items = mutableListOf&lt;String>()

Column {
    for (item in items) {
        Text(item)
    }

    Button("Add Item") {
        items.add("New Item") // 会自动刷新列表
    }
}

注意：

直接替换整个集合 可以触发更新 items = items + listOf("Item2")
集合内部元素修改（如 items[0] = "X") 不一定触发 UI，需整体替换或使用特殊方法

四、@State 与生命周期

@State 变量与 Composable 生命周期绑定
页面退出时，@State 会自动销毁
适合用于 临时 UI 状态
对于跨页面或跨组件共享状态，建议使用 @AppStorage / ViewModel / StateStore

五、@State 的限制与注意事项

不能在非 Composable 外直接使用
- 推荐在 AbilitySlice / Page / Composable 内使用
避免大对象频繁更新
- 大量对象更新会导致性能下降
集合操作需整体替换
- List / Map 内部单个元素修改不会触发 UI
深层对象状态
- 多层嵌套对象，需要每层都用 @State 或使用 immutable 数据结构

六、@State 最佳实践

UI 局部状态
- 用于按钮状态、输入框内容、弹窗显示
全局状态
- 使用 @AppStorage 或自定义 StateStore
集合操作
- 尽量替换整个集合，或使用 mutableListOf().apply { ... }
性能优化
- 避免在循环或大列表中频繁更新单个 @State
- 对于大数据列表，使用 LazyColumn 或 List 渲染

七、完整示例

@Composable
fun CounterPage() {
    @State var counter = 0

    Column(horizontalAlignment = Alignment.Center) {
        Text("Counter: $counter")
        Button("Increment") {
            counter += 1
        }
        Button("Reset") {
            counter = 0
        }
    }
}

效果：

点击 Increment 自动刷新 Text
点击 Reset 重置计数器
无需手动刷新界面

八、总结

@State 是 HarmonyOS 5 ArkUI 响应式数据核心
自动管理 UI 与状态绑定，提高开发效率
适合小范围页面状态管理
对于全局或复杂状态，需要结合 ViewModel / StateStore

退出移动版