メインコンテンツにスキップ

class Snapshot

Snapshotオブジェクトは、Recoilのatomsの状態を表すイミュータブルなスナップショットです。これは、グローバルなRecoil状態を観察、検査、管理するためのAPIを標準化することを目的としています。主に、開発ツール、グローバルな状態同期、履歴ナビゲーションなどに役立ちます。

class Snapshot {
  retain(): () => void;
  isRetained(): boolean;

  // Accessors to inspect snapshot state
  getLoadable: <T>(RecoilValue<T>) => Loadable<T>;
  getPromise: <T>(RecoilValue<T>) => Promise<T>;

  // API to transform state to a new immutable Snapshot
  map: (MutableSnapshot => void) => Snapshot;
  asyncMap: (MutableSnapshot => Promise<void>) => Promise<Snapshot>;

  // Get a StoreID similar to useRecoilStoreID()
  getStoreID: () => StoreID;

  // Developer Tools API
  getID: () => SnapshotID;
  getNodes_UNSTABLE: ({
    isModified?: boolean,
  } | void) => Iterable<RecoilValue<mixed>>;
  getInfo_UNSTABLE: <T>(RecoilValue<T>) => {...};
}

function snapshot_UNSTABLE(initializeState?: (MutableSnapshot => void)): Snapshot

スナップショットの取得​

フック​

Recoilは、現在の状態に基づいてスナップショットを取得するための以下のフックを提供します。

  • useRecoilCallback() - スナップショットへの非同期アクセス。
  • useRecoilSnapshot() - スナップショットへの同期アクセス。
    • このフックを使用すると、コンポーネントはすべてのRecoil状態の変更に対して再レンダリングをサブスクライブします。
  • useRecoilTransactionObserver_UNSTABLE() - すべての状態変更のスナップショットをサブスクライブします。

新しいスナップショットの作成​

snapshot_UNSTABLE()ファクトリーを使用して、新しいスナップショットを作成することもできます。これは、テストやReactコンテキスト外でのセレクターの評価に使用できます。スナップショット内のすべてのアトムはデフォルトの状態から開始されますが、アトムエフェクトは引き続き実行され、アトムを動的な値に初期化できます。snapshot_UNSTABLE()は、状態を初期化するためのオプションのコールバックも受け入れますが、アトムエフェクトの初期化が優先されます。また、セレクターキャッシュはRecoilルートとスナップショット間で共有されますが、コールバックを使用してクリアできることに注意してください。

スナップショットの読み取り​

スナップショットはアトムの状態に関して読み取り専用です。これらを使用して、アトムの状態を読み取り、セレクターの派生状態を評価できます。getLoadable()は、このスナップショットのアトムまたはセレクターの状態を持つLoadableを提供します。getPromise()メソッドを使用すると、非同期セレクターの評価された値を待機できるため、静的なアトムの状態に基づいてどのような値になるかを確認できます。

例​

function MyComponent() {
  const logState = useRecoilCallback(({snapshot}) => () => {
    console.log("State: ", snapshot.getLoadable(myAtom).contents);

    const newSnapshot = snapshot.map(({set}) => set(myAtom, 42));
  });
}

スナップショットの変換​

スナップショットをミューテートしたい場合があります。スナップショットはイミュータブルですが、一連の変換を使用して自身を新しいイミュータブルなスナップショットにマッピングするメソッドがあります。マップメソッドは、MutableSnapshotを渡すコールバックを受け入れます。MutableSnapshotはコールバック全体でミューテートされ、最終的にマッピング操作によって返される新しいスナップショットになります。

class MutableSnapshot {
  set: <T>(RecoilState<T>, T | DefaultValue | (T => T | DefaultValue)) => void;
  reset: <T>(RecoilState<T>) => void;
}

set()とreset()は、書き込み可能なセレクターのsetプロパティに提供されるコールバックと同じシグネチャを持つことに注意してください。ただし、これらは現在の状態ではなく、新しいスナップショットにのみ影響します。

スナップショットへの移動​

以下のフックを使用して、指定されたSnapshotと一致するように現在のRecoil状態を更新できます。

スナップショットの非同期使用​

スナップショットは、取得したコールバックの期間のみ保持されます。それ以降に使用するには、retain()を使用して明示的に保持する必要があります。

test('My Test', async () => {
  const testSnapshot = snapshot_UNSTABLE();
  const releaseSnapshot = initialSnapshot.retain();

  try {
    await something;
    ... use testSnapshot ...
  } finally {
    releaseSnapshot();
  }
});
function MyComponent() {
  const myCallback = useRecoilCallback(({snapshot}) => () => {
    const release = snapshot.retain();
    setTimeout(() => {
      ... use snapshot ...
      release();
    }, 1000);
  });

  ...
}

非同期セレクターは、キャンセルされないように、いくつかの<RecoilRoot>またはSnapshotによってアクティブに使用されている必要があることに注意してください。スナップショットを介してのみ非同期セレクターにアクセスしている場合は、解決済みの値を観察できることを保証するために、それらを保持する必要があります。

開発者ツール​

スナップショットは、Recoilで開発者ツールを構築したり、デバッグ機能を使用したりするのに役立ついくつかのメソッドを提供します。このAPIはまだ進化中であるため、最初の開発ツールに取り組んでいるため、_UNSTABLEとしてマークされています。

スナップショットID​

コミットされた各状態またはミューテートされたスナップショットには、getID()を介して取得できる一意の不透明なバージョンIDがあります。これは、useGotoRecoilSnapshot()を介して前のスナップショットに戻ったかどうかを検出するために使用できます。

アトムとセレクターの列挙​

getNodes_UNSTABLE()メソッドを使用すると、このスナップショットで使用されていたすべてのアトムとセレクターを反復処理できます。アトム、セレクター、およびファミリはいつでも作成できます。ただし、実際に使用されている場合にのみスナップショットに表示されます。アトムとセレクターは、使用されなくなった場合、後続の状態スナップショットから削除される場合があります。

オプションのisModifiedフラグを指定して、最後のトランザクション以降に変更されたアトムのみを返すように指定できます。

デバッグ情報​

getInfo_UNSTABLE()メソッドは、アトムとセレクターの追加のデバッグ情報を提供します。提供されるデバッグ情報は進化していますが、以下が含まれる場合があります。

  • loadable - 現在の状態を持つLoadable。getLoadable()のようなメソッドとは異なり、このメソッドはスナップショットをまったくミューテートしません。現在の状態を提供し、新しいアトム/セレクターを初期化したり、新しいセレクター評価を実行したり、依存関係やサブスクリプションを更新したりすることはありません。
  • isSet - これが、スナップショットの状態に明示的な値が格納されているアトムの場合はTrue。これがセレクターであるか、デフォルトのアトム状態を使用している場合はFalse。
  • isModified - これが、最後のトランザクション以降に変更されたアトムの場合はTrue。
  • type - atomまたはselectorのいずれか
  • deps - このノードが依存するアトムまたはセレクターに対するイテレーター。
  • subscribers - このスナップショットのこのノードをサブスクライブしているものに関する情報。開発中の詳細。

これはuseGetRecoilValueInfo_UNSTABLE()フックに似ていますが、現在の状態ではなく、Snapshotの状態に基づいて情報を提供します。サブスクライブしているReactコンポーネントなど、Recoil状態のスナップショットに関連付けられていない情報を提供することはできません。

状態の初期化​

<RecoilRoot>コンポーネントとsnapshot_UNSTABLE()ファクトリーは、MutableSnapshotを介して状態を初期化するためのオプションのinitializeStateプロップを受け入れます。これは、すべてのアトムを事前に把握している場合に永続化された状態をロードするのに役立ち、最初のレンダリングで状態を同期的に設定する必要があるサーバーサイドレンダリングと互換性があります。アトムごとの初期化/永続化、および動的なアトムを操作しやすくするために、アトムエフェクトを検討してください。

function MyApp() {
  function initializeState({set}) {
    set(myAtom, 'foo');
  }

  return (
    <RecoilRoot initializeState={initializeState}>
      ...
    </RecoilRoot>
  );
}