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 のパターンは、この 2 つだけです。独自の 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);
}