useActionState |
Utilise un état d'action |
|---|---|
| React | |
Syntaxe
| const [state, formAction, isPending] = useActionState(fn, initialState, permalink?); |
Description
useActionState est un crochet permettant de mettre à jour l'état en fonction du résultat d'une action sur un formulaire.
Remarque
- Dans les versions précédentes de React Canary, cette API faisait partie de React DOM et était appelée useFormState.
Référence
| useActionState(action, initialState, permalink?) |
Appelez la fonction useActionState au niveau principal de votre composante pour créer un état de composante étant mis à jour lors de l'exécution d'une action du formulaire. Vous devez passer à useActionState une fonction d'action de formulaire existante ainsi qu'un état initial. La fonction retournera alors une nouvelle action à utiliser dans votre formulaire, ainsi que le dernier état du formulaire et l'état de l'action (en cours ou terminée). Le dernier état du formulaire sera également transmis à la fonction que vous avez fournie.
L'état du formulaire correspond à la valeur renvoyée par l'action lors de la dernière soumission. Si le formulaire n'a pas encore été soumis, il correspond à l'état initial que vous avez défini.
Lorsqu'il est utilisé avec une fonction serveur, useActionState permet d'afficher la réponse du serveur suite à la soumission du formulaire, même avant la finalisation du chargement de la page.
Consultez les exemples ci-dessous pour plus d'informations.
Paramètres
| Nom | Description |
|---|---|
| fn | Cette fonction sera appelée lors de la soumission du formulaire ou du clic sur le bouton. Lors de son appel, elle recevra en premier argument l'état précédent du formulaire (initialement l'état initial que vous avez défini, puis la valeur de retour précédente), suivi des arguments habituels d'une action de formulaire. |
| initialState | Valeur initiale que vous souhaitez attribuer à l'état. Il peut s'agir de n'importe quelle valeur sérialisable. Cet argument est ignoré après le premier appel de l'action. |
| permalink | Une chaîne de caractères contenant l'URL unique de la page modifiée par ce formulaire. À utiliser sur les pages à contenu dynamique (par exemple, les flux de données) en complément de la technique de « progressive enhancement » : si la fonction « fn » est une fonction serveur et que le formulaire est soumis avant le chargement du script JavaScript, le navigateur redirigera l'utilisateur vers l'URL permanente spécifiée, et non vers l'URL de la page actuelle. Assurez-vous que le même composant de formulaire soit affiché sur la page de destination (avec la même fonction « action » et la même URL permanente) afin que React puisse gérer correctement le passage de l'état. Une fois le formulaire initialisé, ce paramètre n'a plus d'effet. |
Valeur de retour
La fonction useActionState renvoie un tableau contenant les éléments suivants :
- L'état actuel. Lors du premier rendu, il correspond à l'état initial que vous avez spécifié. Après l'exécution de l'action, il correspond à la valeur retournée par cette action.
- Une nouvelle fonction d'action que vous pouvez passer en tant que propriété « action » à votre composante de formulaire ou en tant que propriété « formAction » à tout bouton présent dans le formulaire. Cette fonction peut également être appelée manuellement dans la méthode startTransition.
- Un indicateur isPending qui vous informe de l'existence d'une transition en cours.
Remarques
- Lorsque useActionState est utilisé avec un cadre d'application compatible avec les composants côté serveur de React, il permet de rendre les formulaires interactifs avant même que le code JavaScript ne soit exécuté côté client. En revanche, sans l'utilisation de composantes côté serveur, il équivaut au gestionnaire d'état local de la composante.
- La fonction passée à useActionState reçoit un argument supplémentaire : l'état précédent ou initial. Cela modifie sa signature par rapport à une utilisation directe de cette fonction comme action de formulaire sans utiliser useActionState.
Utilisation
Utilisation des informations renvoyées par une action de formulaire.
Appelez la fonction `useActionState` au niveau supérieur de votre composante pour accéder à la valeur de retour de l'action lors du dernier envoi du formulaire.
La fonction useActionState renvoie un tableau contenant les éléments suivants :
- L'état actuel du formulaire, initialement défini par l'état initial que vous avez spécifié, et qui, après soumission du formulaire, correspond à la valeur de retour de l'action que vous avez définie.
- Une nouvelle action que vous pouvez passer à l'élément <form> via la propriété «action» ou appeler manuellement dans la fonction startTransition.
- Un état de chargement en cours, que vous pouvez utiliser pendant le traitement de l'action.
Lors de la soumission du formulaire, la fonction d'action que vous avez définie sera appelée. Sa valeur de retour deviendra le nouvel état actuel du formulaire.
Cette fonction recevra également un nouveau paramètre : l'état actuel du formulaire. Lors de la première soumission, ce paramètre correspondra à l'état initial que vous avez défini ; pour les soumissions suivantes, il correspondra à la valeur de retour de l'appel précédent de la fonction. Les autres arguments restent inchangés, comme si la fonction `useActionState` n'avait pas été utilisée.