状态管理

介绍

状态管理模块（core/state）提供框架级的全局状态，如断点状态和安全区状态。这些状态与业务无关，可直接复用到其他项目。

与 foundation/biz_state 的区别

模块	内容	示例
core/state	框架级状态，与业务无关	BreakpointState、WindowSafeAreaState
foundation/biz_state	业务状态	UserState、DemoCounterState

业务相关的状态（如用户状态、计数器状态）已移至 foundation/biz_state，详见 业务状态 文档。

断点状态

断点状态用于响应式布局，根据屏幕宽度自动切换断点类型。

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

import { AppStorageV2 } from "@kit.ArkUI";
import { BreakpointType } from "./model/BreakpointModel";

export const BREAKPOINT_STATE_KEY: string = "breakpoint_state";

@ObservedV2
export class BreakpointState {
  /**
   * 当前断点类型
   */
  @Trace
  currentBreakpoint: BreakpointType = BreakpointType.SM;

  /**
   * 更新断点
   */
  updateBreakpoint(breakpoint: BreakpointType): void {
    this.currentBreakpoint = breakpoint;
  }
}

/**
 * 获取断点状态实例
 */
export function getBreakpointState(): BreakpointState {
  return AppStorageV2.connect<BreakpointState>(
    BreakpointState,
    BREAKPOINT_STATE_KEY,
    () => new BreakpointState()
  )!;
}

/**
 * 根据断点返回对应值
 */
export function bp<T>(sm: T, md: T, lg: T): T {
  const state = getBreakpointState();
  switch (state.currentBreakpoint) {
    case BreakpointType.SM:
      return sm;
    case BreakpointType.MD:
      return md;
    case BreakpointType.LG:
      return lg;
    default:
      return sm;
  }
}

断点类型

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

/**
 * 断点类型枚举
 */
export enum BreakpointType {
  SM = "sm",  // 小屏 (< 600vp)
  MD = "md",  // 中屏 (600-840vp)
  LG = "lg"   // 大屏 (> 840vp)
}

安全区状态

安全区状态用于处理刘海屏、底部导航栏等安全区域。

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

import { AppStorageV2 } from "@kit.ArkUI";
import { SafeAreaInsets } from "./model/SafeAreaInsets";

export const WINDOW_SAFE_AREA_STATE_KEY: string = "window_safe_area_state";

@ObservedV2
export class WindowSafeAreaState {
  /**
   * 安全区边距
   */
  @Trace
  safeArea: SafeAreaInsets = { top: 0, bottom: 0, left: 0, right: 0 };

  /**
   * 更新安全区
   */
  updateSafeArea(insets: SafeAreaInsets): void {
    this.safeArea = insets;
  }
}

/**
 * 获取安全区状态实例
 */
export function getWindowSafeAreaState(): WindowSafeAreaState {
  return AppStorageV2.connect<WindowSafeAreaState>(
    WindowSafeAreaState,
    WINDOW_SAFE_AREA_STATE_KEY,
    () => new WindowSafeAreaState()
  )!;
}

使用示例

响应式布局

import { bp, getBreakpointState } from "@core/state";

@Component
struct ResponsiveLayout {
  build() {
    Column() {
      // 根据断点返回不同的列数
      GridRow({ columns: bp(2, 3, 4) }) {
        // ...
      }
    }
    .padding(bp(16, 24, 32))
  }
}

安全区适配

import { getWindowSafeAreaState } from "@core/state";

@Component
struct SafeAreaLayout {
  private safeAreaState = getWindowSafeAreaState();

  build() {
    Column() {
      // 内容
    }
    .padding({
      top: this.safeAreaState.safeArea.top,
      bottom: this.safeAreaState.safeArea.bottom
    })
  }
}

AppStorageV2 与 PersistenceV2

• AppStorageV2：应用全局 UI 状态存储，适合临时状态。
• PersistenceV2：持久化存储 UI 状态，适合需要保留的数据。

官方文档：

• AppStorageV2
• PersistenceV2

注意事项

• core/state 只放框架级状态，业务状态放在 foundation/biz_state。
• 只有标注 @Trace 的字段才会触发 UI 响应更新。
• 使用 bp() 函数可以简化响应式布局的代码。