useSyncExternalStore |
Utilise l'entreposage de synchronisation externe |
|---|---|
| React | |
Syntaxe
| const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?) |
Description
useSyncExternalStore est un crochet React vous permettant de vous abonner à un magasin externe.
Référence
| useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?) |
Appelez useSyncExternalStore au niveau supérieur de votre composant pour lire une valeur à partir d'un magasin de données externe.
- import { useSyncExternalStore } from 'react';
- import { todosStore } from './todoStore.js';
-
- function TodosApp() {
- const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);
- // ...
- }
Elle renvoie un instantané des données du magasin. Vous devez passer deux fonctions en paramètres :
- La fonction subscribe doit s'abonner au magasin et renvoyer une fonction de désabonnement.
- La fonction getSnapshot doit lire un instantané des données du magasin.
Paramètres
| Nom | Description |
|---|---|
| subscribe | Fonction prenant un seul paramètre de rappel et l'abonne au magasin. Lorsque le magasin change, elle doit invoquer le rappel fourni, ce qui force React à rappeler getSnapshot et, si nécessaire, à restituer la composante. La fonction subscribe doit renvoyer une fonction nettoyant l'abonnement. |
| getSnapshot | Fonction renvoyant un instantané des données du magasin requises par la composante. Tant que le magasin n'a pas changé, les appels répétés à getSnapshot doivent renvoyer la même valeur. Si le magasin change et que la valeur renvoyée est différente (par rapport à Object.is), React restitue la composante. |
| getServerSnapshot | (optionnel) Fonction qui renvoie l'instantané initial des données du magasin. Elle sera utilisée uniquement lors du rendu serveur et lors de l'hydratation du contenu rendu serveur sur le client. L'instantané serveur doit être identique entre les deux serveurs, et est généralement sérialisé et transmis du serveur au client. Si vous omettez ce paramètre, le rendu de composante sur le serveur générera une erreur. |
Renvoie
L'instantané actuel du store, utilisable dans votre logique de rendu.
Avertissements
L'instantané du store renvoyé par getSnapshot doit être immuable. Si le store sous-jacent contient des données mutables, renvoyez un nouvel instantané immuable si les données ont changé. Sinon, renvoyez le dernier instantané mis en cache.
Si une fonction d'abonnement différente est transmise lors d'un nouveau rendu, React se réabonnera au store à l'aide de la nouvelle fonction. Vous pouvez éviter cela en déclarant subscribe en dehors de la composante.
Si le store subit une mutation lors d'une mise à jour de transition non bloquante, React effectuera cette mise à jour comme bloquante. Plus précisément, pour chaque mise à jour de transition, React appellera getSnapshot une deuxième fois juste avant d'appliquer les modifications au DOM. Si la valeur renvoyée est différente de celle de l'appel initial, React relancera la mise à jour depuis le début, l'appliquant cette fois comme une mise à jour bloquante, afin de garantir que tous les composants à l'écran reflètent la même version du store.
Il est déconseillé de suspendre un rendu en fonction d'une valeur de magasin renvoyée par useSyncExternalStore. En effet, les mutations du magasin externe ne peuvent pas être marquées comme des mises à jour de transition non bloquantes. Elles déclencheront donc la solution de repli Suspense la plus proche, remplaçant le contenu déjà affiché à l'écran par un indicateur de chargement, ce qui nuit généralement à l'expérience utilisateur.
Par exemple, les éléments suivants sont déconseillés :
- const LazyProductDetailPage = lazy(() => import('./ProductDetailPage.js'));
-
- function ShoppingApp() {
- const selectedProductId = useSyncExternalStore(...);
-
- // Appel de «use» avec une promesse dépendante de «selectedProductId»
- const data = use(fetchItem(selectedProductId))
-
- // Rendu conditionnel d'une composante paresseux basé sur «selectedProductId»
- return selectedProductId != null ? <LazyProductDetailPage /> : <FeaturedProducts />;
- }
Utilisation
S'abonner à un magasin externe
La plupart de vos composantes React lisent uniquement les données de leurs propriétés, de leur état et de leur contexte. Cependant, il arrive qu'une composante doive lire des données provenant d'un magasin externe à React, évoluant au fil du temps. Cela inclut :
- Bibliothèques de gestion d'état tierces qui conservent l'état en dehors de React.
- API de navigateur qui exposent une valeur modifiable et des événements permettant de s'abonner à ses modifications.
Appelez useSyncExternalStore au niveau supérieur de votre composante pour lire une valeur depuis un magasin de données externe.
- import { useSyncExternalStore } from 'react';
- import { todosStore } from './todoStore.js';
-
- function TodosApp() {
- const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);
- // ...
- }
Elle renvoie un instantané des données du magasin. Vous devez passer deux fonctions en paramètres :
- La fonction subscribe doit s'abonner au magasin et renvoyer une fonction permettant de se désabonner.
- La fonction getSnapshot doit lire un instantané des données du magasin.
- React utilisera ces fonctions pour maintenir l'abonnement de votre composante au magasin et le restituer en cas de modification.
Par exemple, dans le sandbox ci-dessous, todosStore est implémenté comme un magasin externe entreposant les données en dehors de React. La composante TodosApp se connecte à ce magasin externe avec le crochet useSyncExternalStore.