Back to Details

1k-state-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OneKey State Management

OneKey状态管理

Jotai Atom Organization - MANDATORY STRUCTURE

Jotai Atom 组织规范 - 强制遵循结构

Global State Atoms (for app-wide, persistent state)

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

  • Location: 
    packages/kit-bg/src/states/jotai/atoms/
  • Usage: Global settings, account state, hardware state, currency, etc.
  • Pattern: Use 
    globalAtom
    and 
    EAtomNames
    for standardization
  • Examples: 
    settings.ts
    , 
    account.ts
    , 
    hardware.ts
    , 
    currency.ts
  • 存放位置：
    packages/kit-bg/src/states/jotai/atoms/
  • 用途：全局设置、账户状态、硬件状态、货币信息等
  • 模式：使用
    globalAtom
    和
    EAtomNames
    实现标准化
  • 示例文件：
    settings.ts
    , 
    account.ts
    , 
    hardware.ts
    , 
    currency.ts

Feature-Specific State Atoms (for localized functionality)

功能专属状态Atoms（用于局部功能模块）

  • Location: 
    packages/kit/src/states/jotai/contexts/[feature_name]/atoms.ts
  • Usage: Feature-specific state that may be shared across components within that feature
  • Pattern: Use 
    contextAtom
    from 
    createJotaiContext
    for consistency
  • Structure: 
    contexts/
├── marketV2/
│   ├── atoms.ts     - State definitions
│   ├── actions.ts   - State operations
│   └── index.ts     - Exports
├── swap/
│   ├── atoms.ts
│   ├── actions.ts
│   └── index.ts
  • 存放位置：
    packages/kit/src/states/jotai/contexts/[feature_name]/atoms.ts
  • 用途：特定功能模块内的状态，可在该功能的多个组件间共享
  • 模式：使用
    createJotaiContext
    提供的
    contextAtom
    以保持一致性
  • 目录结构: 
    contexts/
├── marketV2/
│   ├── atoms.ts     - 状态定义
│   ├── actions.ts   - 状态操作
│   └── index.ts     - 导出文件
├── swap/
│   ├── atoms.ts
│   ├── actions.ts
│   └── index.ts

FORBIDDEN Atom Patterns

禁止使用的Atom模式

  • ❌ NEVER create atom directories under 
    packages/kit/src/views/
  • ❌ NEVER create standalone atom files in component directories
  • ❌ NEVER mix 
    globalAtom
    and 
    contextAtom
    patterns without architectural justification
  • ❌ 绝对不要在
    packages/kit/src/views/
    目录下创建Atom文件夹
  • ❌ 绝对不要在组件目录下创建独立的Atom文件
  • ❌ 绝对不要在无架构设计依据的情况下混合使用
    globalAtom
    和
    contextAtom
    模式

Atom Selection Guidelines

Atom选择指南

Use globalAtom when:

当满足以下条件时使用
globalAtom
:

  • State needs persistence across app restarts
  • State is used across multiple major features
  • State affects the entire application (settings, authentication, etc.)
  • Located in 
    packages/kit-bg/src/states/jotai/atoms/
  • 状态需要在应用重启后仍保持持久化
  • 状态需在多个核心功能模块间共享
  • 状态影响整个应用（如设置、认证信息等）
  • 存放于
    packages/kit-bg/src/states/jotai/atoms/
    目录下

Use contextAtom when:

当满足以下条件时使用
contextAtom
:

  • State is specific to a feature or module
  • State is temporary/session-based
  • State is shared within related components of a feature
  • Located in 
    packages/kit/src/states/jotai/contexts/[name]/atoms.ts
IMPORTANT: These are the ONLY two atom patterns used in the project. Do not create custom atom patterns or use plain Jotai atoms outside of these established structures.
  • 状态仅属于某个特定功能或模块
  • 状态为临时/会话级（无需持久化）
  • 状态仅在某功能的关联组件间共享
  • 存放于
    packages/kit/src/states/jotai/contexts/[name]/atoms.ts
    目录下
重要提示：项目中仅允许使用这两种Atom模式。请勿自定义Atom模式，也不要在这些既定结构之外使用原生Jotai atoms。

Common Patterns

常见实现模式

Creating a Global Atom

创建全局Atom

typescript
// 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
});
typescript
// 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: { /* 初始状态 */ },
  persist: true, // 若需要持久化则设为true
});

Creating a Context Atom

创建上下文Atom

typescript
// 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 };
typescript
// packages/kit/src/states/jotai/contexts/myFeature/atoms.ts
import { createJotaiContext } from '../../utils';

const { contextAtom, useContextAtom } = createJotaiContext();

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

// 导出供组件使用的Hook
export { useContextAtom };

Using Atoms in Components

在组件中使用Atoms

typescript
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);
}
typescript
import { useAtom, useAtomValue, useSetAtom } from 'jotai';
import { myFeatureAtom } from '@onekeyhq/kit-bg/src/states/jotai/atoms';

function MyComponent() {
  // 读写状态
  const [value, setValue] = useAtom(myFeatureAtom);

  // 仅读取状态
  const value = useAtomValue(myFeatureAtom);

  // 仅修改状态
  const setValue = useSetAtom(myFeatureAtom);
}