Aller au contenu principal

atomFamily(options)

Renvoie une fonction qui renvoie un RecoilState atom inscriptible.


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 - Une chaĂźne unique utilisĂ©e pour identifier l'atome en interne. Cette chaĂźne doit ĂȘtre unique par rapport aux autres atomes et sĂ©lecteurs dans l'ensemble de l'application.
  • default - La valeur initiale de l'atome. Il peut s'agir soit directement d'une valeur, d'une RecoilValue ou d'une Promise qui reprĂ©sente la valeur par dĂ©faut, ou d'une fonction pour obtenir la valeur par dĂ©faut. La fonction de rappel reçoit une copie du paramĂštre utilisĂ© lorsque la fonction atomFamily est appelĂ©e.
  • effects_UNSTABLE - Un tableau facultatif, ou une fonction de rappel pour obtenir le tableau basĂ© sur le paramĂštre de famille, voire Effets Atomiques.
  • dangerouslyAllowMutability - Recoil dĂ©pend des changements d'Ă©tat de l'atome pour savoir quand notifier les composants qui utilisent les atomes pour effectuer un nouveau rendu. Si la valeur d'un atome a Ă©tĂ© mutĂ©e, il peut contourner cela et provoquer un changement d'Ă©tat sans notifier correctement les composants abonnĂ©s. Pour vous protĂ©ger contre cela, toutes les valeurs stockĂ©es sont gelĂ©es. Dans certains cas, il peut ĂȘtre souhaitable de remplacer cette option en utilisant cette option.

Un atome reprĂ©sente un morceau d'Ă©tat avec Recoil. Un atome est crĂ©Ă© et enregistrĂ© par <RecoilRoot> par votre application. Mais que se passe-t-il si votre Ă©tat n’est pas mondial? Que faire si votre Ă©tat est associĂ© Ă  une instance particuliĂšre d'un contrĂŽle ou Ă  un Ă©lĂ©ment particulier? Par exemple, votre application est peut-ĂȘtre un outil de prototypage d'interface utilisateur dans lequel l'utilisateur peut ajouter dynamiquement des Ă©lĂ©ments et chaque Ă©lĂ©ment a un Ă©tat, tel que sa position. IdĂ©alement, chaque Ă©lĂ©ment aurait son propre atome d'Ă©tat. Vous pouvez l'implĂ©menter vous-mĂȘme via un modĂšle de mĂ©morisation. Mais, Recoil fournit ce modĂšle pour vous avec l'utilitaire atomFamily. Une famille d'atomes reprĂ©sente une collection d'atomes. Lorsque vous appelez atomFamily, il retournera une fonction qui fournit l'atome RecoilState en fonction des paramĂštres que vous passez.

AtomFamily fournit essentiellement une carte du paramĂštre Ă  un atome. Il vous suffit de fournir une clĂ© unique pour atomFamily et elle gĂ©nĂ©rera une clĂ© unique pour chaque atome sous-jacent. Ces clĂ©s atom peuvent ĂȘtre utilisĂ©es pour la persistance et doivent donc ĂȘtre stables entre les exĂ©cutions d'application. Les paramĂštres peuvent Ă©galement ĂȘtre gĂ©nĂ©rĂ©s sur diffĂ©rents sites d'appel et nous voulons que des paramĂštres Ă©quivalents utilisent le mĂȘme atome sous-jacent. Par consĂ©quent, l'Ă©galitĂ© des valeurs est utilisĂ©e Ă  la place de l'Ă©galitĂ© des rĂ©fĂ©rences pour les paramĂštres atomFamily. Cela impose des restrictions sur les types qui peuvent ĂȘtre utilisĂ©s pour le paramĂštre. atomFamily accepte des types primitifs, ou des tableaux ou des objets qui peuvent contenir des tableaux, des objets ou des types primitifs.

Exemple​

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

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

Un atomFamily() prend presque les mĂȘmes options qu'un simple [atom()](/docs/api-reference/ core/atom). Cependant, la valeur par dĂ©faut peut Ă©galement ĂȘtre paramĂ©trĂ©e. Cela signifie que vous pouvez fournir une fonction qui prend la valeur du paramĂštre et renvoie la valeur par dĂ©faut rĂ©elle. Par exemple:

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

ou en utilisant selectorFamily au lieu de selector, vous pouvez également accéder à la valeur du paramÚtre dans un sélecteur default.

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

Abonnements​

Un avantage de l'utilisation de ce modÚle pour des atomes séparés pour chaque élément par rapport à essayer de stocker un seul atome avec une carte d'état pour tous les éléments est qu'ils maintiennent tous leurs propres abonnements individuels. Ainsi, la mise à jour de la valeur d'un élément entraßnera uniquement la mise à jour des composants React qui se sont abonnés uniquement à cet atome.

Persistance​

Les observateurs de persistance conserveront l'état de chaque valeur de paramÚtre en tant qu'atome distinct avec une clé unique basée sur la sérialisation de la valeur de paramÚtre utilisée. Par conséquent, il est important de n'utiliser que des paramÚtres qui sont des primitives ou de simples objets composés contenant des primitives. Les classes ou fonctions personnalisées ne sont pas autorisées.

Il est permis de "promouvoir" un simple atom pour en faire un atomFamily dans une version plus rĂ©cente de votre application basĂ©e sur la mĂȘme clĂ©. Si vous faites cela, alors toutes les valeurs persistantes avec l'ancienne clĂ© simple peuvent toujours ĂȘtre lues et toutes les valeurs de paramĂštres de la nouvelle atomFamily seront par dĂ©faut Ă  l'Ă©tat persistant de l'atome simple. Si vous modifiez le format du paramĂštre dans une atomFamily, cependant, il ne lira pas automatiquement les valeurs prĂ©cĂ©dentes qui Ă©taient conservĂ©es avant la modification. Cependant, vous pouvez ajouter une logique dans un sĂ©lecteur ou un validateur par dĂ©faut pour rechercher des valeurs basĂ©es sur les formats de paramĂštres prĂ©cĂ©dents. Nous espĂ©rons aider Ă  automatiser ce modĂšle Ă  l'avenir.