状态管理

介绍

状态管理模块用于全局共享状态。实际项目可以根据需求选择 AppStorageV2 或 PersistenceV2，这里用计数器做最小示例演示基本用法。

核心思路

• 全局状态统一放在 state 模块。
• 通过 AppStorageV2.connect 获取全局实例。
• ViewModel 只操作状态对象，不直接管理 UI。

AppStorageV2 与 PersistenceV2

• AppStorageV2：应用全局 UI 状态存储，适合临时状态。
  文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-appstoragev2
• PersistenceV2：持久化存储 UI 状态，适合保存用户信息等需要持久化的数据。
  文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-persistencev2

状态定义示例

文件位置：core/state/src/main/ets/DemoCounterState.ets

import { AppStorageV2 } from "@kit.ArkUI";

/**
 * @file 全局计数器状态
 */
export const DEMO_COUNTER_KEY: string = "demo_counter_state";

@ObservedV2
export class DemoCounterState {
  /**
   * 当前计数
   */
  @Trace
  count: number = 0;

  /**
   * 计数加一
   * @param {number} step - 步长，默认 1
   * @returns {void} 无返回值
   */
  increment(step: number = 1): void {
    this.count += step;
  }

  /**
   * 计数减一
   * @param {number} step - 步长，默认 1
   * @returns {void} 无返回值
   */
  decrement(step: number = 1): void {
    if (this.count - step < 0) {
      this.count = 0;
      return;
    }
    this.count -= step;
  }

  /**
   * 重置计数
   * @param {number} resetValue - 重置值，默认 0
   * @returns {void} 无返回值
   */
  reset(resetValue: number = 0): void {
    this.count = resetValue;
  }
}

/**
 * 获取全局计数器状态实例；若不存在则创建
 * @returns {DemoCounterState} 全局计数器状态
 */
export function getDemoCounterState(): DemoCounterState {
  return AppStorageV2.connect<DemoCounterState>(
    DemoCounterState,
    DEMO_COUNTER_KEY,
    () => new DemoCounterState()
  )!;
}

ViewModel 使用示例

文件位置：feature/demo/src/main/ets/viewmodel/StateManagementViewModel.ets

import { BaseViewModel } from "base";
import { DemoCounterState, getDemoCounterState } from "state";

/**
 * @file 状态管理示例页 ViewModel
 */
@ObservedV2
export default class StateManagementViewModel extends BaseViewModel {
  /**
   * 计数器状态
   */
  @Trace
  counterState: DemoCounterState = getDemoCounterState();

  /**
   * 计数加一
   * @returns {void} 无返回值
   */
  increment(): void {
    this.counterState.increment();
  }

  /**
   * 计数减一
   * @returns {void} 无返回值
   */
  decrement(): void {
    this.counterState.decrement();
  }

  /**
   * 重置计数
   * @returns {void} 无返回值
   */
  reset(): void {
    this.counterState.reset();
  }
}

如何新增状态

1. 在 core/state/src/main/ets/ 新建状态类，使用 @ObservedV2。
2. 需要响应更新的字段加 @Trace。
3. 通过 AppStorageV2.connect 或 PersistenceV2.connect 暴露获取方法。
4. 在 core/state/Index.ets 中补充导出。

注意事项

• 只有标注 @Trace 的字段才会触发 UI 响应更新。
• 临时状态用 AppStorageV2，用户信息等持久化状态用 PersistenceV2。