Recoil公式ドキュメント 翻訳㉘ APIリファレンス-Core-実用(Utils)-atomFamily()

Recoilの公式ドキュメントをgoogle翻訳するとコードまで翻訳されてしまうのが面倒なのでQiitaにまとめてみます。

追々追加していきます。(多分)

公式ドキュメント

目次

• 前書き　①　②　③　④
• 基本チュートリアル　⑤　⑥　⑦
• ガイド　⑧　⑨　⑩
• APIリファレンス
• Core　⑪　⑫　⑬　⑭　⑮　⑯　⑰　⑱　⑲　⑳　㉑　㉒　㉓　㉔　㉕　㉖　㉗
• 実用(utils)
  
  •　㉘ atomFamily()
  
  •　㉙selectorFamily()
  
  •　㉚constSelector()
  
  •　㉛errorSelector()
  
  •　㉜waitForAll()
  
  •　㉝waitForAny()
  
  •　㉞waitForNone()
  
  •　㉟noWait()
  

※全目次は一番下にあります

---

atomFamily(options)

​書き込み可能なRecoilState atomを返す関数を返します。

---

function atomFamily<T, Parameter>({
  key: string,

  default:
    | RecoilValue<T>
    | Promise<T>
    | T
    | (Parameter => T | RecoilValue<T> | Promise<T>),

  effects_UNSTABLE?:
    | $ReadOnlyArray<AtomEffect<T>>
    | (P => $ReadOnlyArray<AtomEffect<T>>),

  dangerouslyAllowMutability?: boolean,
}): Parameter => RecoilState<T>

• ​key - atomを内部的に識別するために使用される一意の文字列。​この文字列は、アプリケーション全体で他のatomおよびselectorに対して一意である必要があります。
• default - atomの初期値。​直接値を指定するか、デフォルト値を表すRecoilValueまたはPromiseを指定するか、あるいはデフォルト値を取得する関数を指定します。​コールバック関数には、atomFamily関数の呼び出し時に使用されるパラメータのコピーが渡されます。
• effects_UNSTABLE - Atom Effectsのオプションの配列、あるいはfamilyパラメータに基づいて配列を取得するためのコールバック。
• dangerouslyAllowMutability - Recoilは、atomのstateの変化に依存して、atomを再描画に使用するコンポーネントに通知するタイミングを決定します。​atomの値が変更された場合、これをバイパスし、登録するコンポーネントに適切に通知せずにstateを変更する可能性があります。​これを防ぐために、保存されている値はすべて凍結されます。​場合によっては、このオプションを使用してこれをオーバーライドすることが望ましいこともあります。

---

​atomはRecoil stateの断片を表します。​atomはごとにアプリケーションによって作成され、登録されます。しかし、stateがグローバルでない場合はどうなりますか？ ​stateがコントロールの特定のインスタンスに関連付けられている場合、または特定の要素に関連付けられている場合はどうなりますか？ ​例えば、あなたのアプリはユーザが動的に要素を追加することができ、各要素はその位置のようなstateを持っているUIプロトタイピングツールかもしれません。​理想的には、各元素はそれぞれのstate atomをもちます。​これはメモパターンを使って自分で実装できます。​しかし、RecoilはatomFamilyユーティリティでこのパターンを提供します。atomFamilyは、atomの集合を表します。​atomFamilyを呼び出すと、渡されたパラメータに基づいてRecoilStateatomを提供する関数が返されます。

​atomFamilyは基本的に、パラメータからatomへのmapを提供します。​atomFamilyに提供する必要があるkeyは1つだけで、基礎となる各atomに固有のkeyが生成されます。​これらのatom keyは持続性のために使用できるため、アプリケーションの実行中に安定している必要があります。​パラメータは異なるコールサイトで生成されることもあり、同じ基底atomを使用する同等のパラメータが必要です。​したがって、atomFamilyパラメータのreference-equalityの代わりにvalue-equalityが使用されます。​これにより、パラメータに使用できるタイプが制限されます。​atomFamilyは、プリミティブ型、または配列、オブジェクト、プリミティブ型を含む配列またはオブジェクトを受け入れます。

サンプルコード

const elementPositionStateFamily = atomFamily({
  key: 'ElementPosition',
  default: [0, 0],
});

function ElementListItem({elementID}) {
  const position = useRecoilValue(elementPositionStateFamily(elementID));
  return (
    <div>
      Element: {elementID}
      Position: {position}
    </div>
  );
}

​atomFamily()は、単純なatom()とほとんど同じオプションを取ります。​ただし、既定値をパラメータ化することもできます。​つまり、パラメータ値を受け取り、実際のデフォルト値を返す関数を提供できます。​たとえば、次のようになります。

const myAtomFamily = atomFamily({
  key: ‘MyAtom’,
  default: param => defaultBasedOnParam(param),
});

またはselectorの代わりにselectorFamilyを使用すると、デフォルトselectorでパラメータ値にアクセスすることもできます。

const myAtomFamily = atomFamily({
  key: ‘MyAtom’,
  default: selectorFamily({
    key: 'MyAtom/Default',
    get: param => ({get}) => {
      return computeDefaultUsingParam(param);
    },
  }),
});

Subscriptions (購読)

​すべての要素のstate mapを持つ単一のatomを保存しようとするよりも、各要素の個別のatomにこのパターンを使用する方が優れている点の1つは、すべての要素がそれぞれ独自のサブスクリプションを保持することです。​そのため、1つの要素の値を更新すると、そのatomのみに登録しているReactコンポーネントのみが更新されます。

Persistence (持続性)

​永続性オブザーバは、使用されるパラメータ値のシリアライズに基づいて一意のkeyを持つ個別のatomとして、各パラメータ値のstateを永続化します。​したがって、プリミティブまたはプリミティブを含む単純な合成オブジェクトであるパラメータのみを使用することが重要です。​カスタムクラスまたは関数は使用できません。

​同じkeyに基づいた新しいバージョンのアプリでは、単純なatomをatomFamilyに"アップグレード"することができます。​これを行うと、古い単純なkeyを持つ永続化された値も引き続き読み取ることができ、新しいatomFamilyのすべてのパラメーター値は、デフォルトで単純なatomの永続化されたstateになります。​ただし、atomFamilyのパラメータのフォーマットを変更した場合、変更前に保持されていた以前の値は自動的に読み込まれません。​ただし、以前のパラメータフォーマットに基づいて値をルックアップする場合は、デフォルトのセレクタまたはバリデータにロジックを追加できます。​将来的には、このパターンの自動化を支援したいと考えています。

---

参考サイト

・公式ドキュメント
・みらい翻訳

---

全目次

• 前書き
• ①動機
• ②コアコンセプト
• ③インストール
• ④入門
• 基本チュートリアル
• ⑤概要
• ⑥Atoms
• ⑦Selectors
• ガイド
• ⑧非同期データクエリ
• ⑨非同期状態・同期状態
• ⑩Stateの永続性
• APIリファレンス
• Core
  
  •　⑪ <RecoilRoot />
  
  •　State
  
  　・　⑫atom()
  
  　・　⑬selector()
  
  　・　⑭Loadable
  
  　・　⑮useRecoilState()
  
  　・　⑯useRecoilValue()
  
  　・　⑰useSetRecoilState()
  
  　・　⑱useResetRecoilState()
  
  　・　⑲useRecoilValueLoadable()
  
  　・　⑳useRecoilStateLoadable()
  
  　・　㉑isRecoilValue()
  
  •　Snapshots
  
  　・　㉒Snapshot
  
  　・　㉓useRecoilTransactionObserver()
  
  　・　㉔useRecoilSnapshot()
  
  　・　㉕useGotoRecoilSnapshot()
  
  •　㉖useRecoilCallback()
  
  •　雑録(Misc)
  
  　・　㉗useRecoilBridgeAcrossReactRoots()
  
• 実用(utils)
  
  •　㉘ atomFamily()
  
  •　㉙selectorFamily()
  
  •　㉚constSelector()
  
  •　㉛errorSelector()
  
  •　㉜waitForAll()
  
  •　㉝waitForAny()
  
  •　㉞waitForNone()
  
  •　㉟noWait()