本文へ移動

<RecoilSync> - Recoil Sync ストア

Recoil Syncライブラリのコンポーネントで、外部ストアを定義し、syncEffect() atomエフェクトを使用してAtomと同期します。

function RecoilSync(props: {
  storeKey?: string,

  read?: ReadItem,
  write?: WriteItems,
  listen?: ListenToItems,

  children: React.Node,
}): React.Node

storeKeyは、どのAtomがこの外部ストアと同期するべきかを突き合わせるために使用されます。

読み込みインターフェース​

read()コールバックは、外部ストアからアイテムを読み取る方法を定義します。これは、外部ストアに基づいてAtomの値を初期化しようとする際に使用されます。複雑なマッピングからも呼び出される可能性があります。

type ReadItem = ItemKey =>
  | DefaultValue
  | Promise<DefaultValue | mixed>
  | Loadable<DefaultValue | mixed>
  | mixed;

ストア内のアイテムの実際の値を返すことができます。アイテムがストアに設定されていないか、利用できない場合は、DefaultValueを返すことができます。非同期操作でストアから読み取る必要がある場合は、値への非同期Promiseを返すことも可能です。必要に応じてエラー状態を提供するために、Loadable表現を返すこともできます。

書き込みインターフェース​

write()コールバックは、Atomの状態が変更されたときに呼び出されるため、これらの変更を外部ストアに書き込む方法を定義できます。

type ItemDiff = Map<ItemKey, DefaultValue | any>;
type ItemSnapshot = Map<ItemKey, DefaultValue | mixed>;

type WriteItems = ({
  diff: ItemDiff,
  allItems: ItemSnapshot,
}) => void;

write()コールバックには、いくつかの名前付きパラメータが提供されます。

  • diff - このアトミックトランザクションで変更されたアイテムキーとその新しい値のマップ。
  • allItems - このストアで使用されたすべてのアイテムのキーと値のマップ。

アイテムの値はDefaultValueオブジェクトである可能性があり、これはアイテムをリセットまたは削除する必要があることを意味します。syncEffect()がsyncDefaultオプションを指定している場合、DefaultValueプレースホルダーオブジェクトではなく、実際のデフォルト値が提供されます。

リスンインターフェース​

listen()コールバックを使用すると、外部ストアからの非同期更新を購読し、Atomの状態を変更して同期を維持できます。

type UpdateItem = <T>(ItemKey, DefaultValue | T) => void;
type UpdateItems = ItemSnapshot => void;
type UpdateAllKnownItems = ItemSnapshot => void;

type ListenToItems = ({
  updateItem: UpdateItem,
  updateItems: UpdateItems,
  updateAllKnownItems: UpdateAllKnownItems,
}) => void | (() => void);

listen()コールバックには、アイテムを新しい値に更新できるコールバックがパラメータとして提供されます。これらのアイテムから読み取ったAtomはすべて「購読」され、更新されたアイテムから読み取ることで状態が更新されます。

  • updateItem() - キーと値を提供することで、単一のアイテムの値を更新します。値がDefaultValueの場合、アイテムはデフォルトにリセットされます。これは単一のアイテムのみを更新し、他のアイテムには影響しません。
  • updateItems() - アイテムキーと値のマップを提供することで、複数のアイテムを更新します。同様に、値がDefaultValueの場合、これらのアイテムはリセットされます。これは提供されたアイテムのみを更新し、他のアイテムには影響しません。
  • updateAllKnownItems() - アイテムキーと値のマップを提供することで、複数のアイテムを更新します。同様に、値がDefaultValueの場合、これらのアイテムはリセットされます。この関数は、このストアと同期しているAtomによって読み取られたすべての既知のアイテムを更新します。つまり、アイテムキーが提供されたマップに含まれていない場合、そのアイテムはデフォルトにリセットされます。

listen()の実装からコールバックハンドラ関数を返すことができます。これは、ストアエフェクトがクリーンアップされたときに呼び出され、外部ストアへの購読をクリーンアップするために使用できます。

例​

"ストアの実装"ガイドに例があります。