1k-state-management

OneKey 状态管理

Jotai Atom 组织方式——强制结构

全局状态 Atom（用于应用级持久化状态）

• 位置：packages/kit-bg/src/states/jotai/atoms/
• 用途：全局设置、账户状态、硬件状态、货币等。
• 模式：使用 globalAtom 和 EAtomNames 以保持标准化
• 示例：settings.ts、account.ts、hardware.ts、currency.ts

功能专属状态 Atom（用于局部功能）

• 位置：packages/kit/src/states/jotai/contexts/[feature_name]/atoms.ts
• 用途：功能专属状态，可在该功能的多个组件间共享
• 模式：使用 createJotaiContext 中的 contextAtom 以保持一致性
• 结构：

  contexts/
  ├── marketV2/
  │   ├── atoms.ts     - State definitions
  │   ├── actions.ts   - State operations
  │   └── index.ts     - Exports
  ├── swap/
  │   ├── atoms.ts
  │   ├── actions.ts
  │   └── index.ts
  

禁止使用的 Atom 模式

• ❌ 绝不要在 packages/kit/src/views/ 下创建 Atom 目录
• ❌ 绝不要在组件目录中创建独立的 Atom 文件
• ❌ 不要在缺乏架构依据的情况下混用 globalAtom 和 contextAtom 模式

Atom 选择指南

在以下情况下使用 globalAtom：

• 状态需要在应用重启后保留
• 多个主要功能都会使用该状态
• 状态会影响整个应用（设置、身份验证等）
• 位于 packages/kit-bg/src/states/jotai/atoms/

在以下情况下使用 contextAtom：

• 状态专属于某个功能或模块
• 状态是临时的／基于会话的
• 状态在某个功能的相关组件间共享
• 位于 packages/kit/src/states/jotai/contexts/[name]/atoms.ts

重要：项目中只使用这两种 Atom 模式。不要创建自定义 Atom 模式，也不要在这些既定结构之外使用普通 Jotai Atom。

常见模式

创建全局 Atom

// packages/kit-bg/src/states/jotai/atoms/myFeature.ts
import { globalAtom } from '../utils';
import { EAtomNames } from '../atomNames';

export const myFeatureAtom = globalAtom<MyFeatureState>({
  name: EAtomNames.myFeature,
  initialValue: { /* initial state */ },
  persist: true, // if persistence needed
});

创建上下文 Atom

// packages/kit/src/states/jotai/contexts/myFeature/atoms.ts
import { createJotaiContext } from '../../utils';

const { contextAtom, useContextAtom } = createJotaiContext();

export const myFeatureDataAtom = contextAtom<MyData | null>(null);

// Export hook for components
export { useContextAtom };

在组件中使用 Atom

import { useAtom, useAtomValue, useSetAtom } from 'jotai';
import { myFeatureAtom } from '@onekeyhq/kit-bg/src/states/jotai/atoms';

function MyComponent() {
  // Read and write
  const [value, setValue] = useAtom(myFeatureAtom);

  // Read only
  const value = useAtomValue(myFeatureAtom);

  // Write only
  const setValue = useSetAtom(myFeatureAtom);
}