Référence de l'API Actions
Ajouté à la version :
astro@4.15.0
Les actions vous aident à créer un backend incluant la sûreté du typage que vous pouvez appeler à partir du code client et des formulaires HTML. Tous les utilitaires permettant de définir et d’appeler des actions sont exposés par le module astro:actions
. Pour des exemples et des instructions d’utilisation, consultez le guide Actions.
Importations depuis astro:actions
Titre de la section Importations depuis astro:actionsdefineAction()
Titre de la section defineAction()
Ajouté à la version :
astro@4.15.0
L’utilitaire defineAction()
est utilisé pour définir de nouvelles actions à partir du fichier src/actions/index.ts
. Il accepte une fonction handler()
contenant la logique du serveur à exécuter et une propriété facultative input
pour valider les paramètres d’entrée lors de l’exécution.
Propriété handler()
Titre de la section Propriété handler()Type : (input, context) => any
defineAction()
nécessite une fonction handler()
contenant la logique du serveur à exécuter lorsque l’action est appelée. Les données renvoyées par le gestionnaire sont automatiquement sérialisées et envoyées à l’appelant.
Le handler()
est appelé avec la saisie de l’utilisateur comme premier argument. Si un validateur input
est défini, la saisie de l’utilisateur sera validée avant d’être transmise au gestionnaire. Le deuxième argument est un objet context
contenant la plupart du contexte de point de terminaison standard d’Astro, à l’exception de getActionResult()
, callAction()
et redirect()
.
Les valeurs de retour sont analysées à l’aide de la bibliothèque devalue. Celle-ci prend en charge les valeurs JSON, ainsi que les instances de Date()
, Map()
, Set()
ou URL()
.
Validateur de saisie (input
)
Titre de la section Validateur de saisie (input)Type : ZodType | undefined
La propriété facultative input
accepte un validateur Zod pour vérifier les entrées du gestionnaire lors de l’exécution. Si l’action échoue à la validation, une erreur BAD_REQUEST
est renvoyée et la fonction handler
n’est pas appelée.
Si input
est omis, le handler
recevra une entrée de type unknown
pour les requêtes JSON et de type FormData
pour les requêtes de formulaire.
Utiliser avec accept: 'form'
Titre de la section Utiliser avec accept: 'form'Si votre action accepte les entrées de formulaire, utilisez le validateur z.object()
pour analyser automatiquement les données du formulaire en un objet typé. Les validateurs suivants sont pris en charge pour les champs de données de formulaire :
- Les entrées de type
number
peuvent être validées à l’aide dez.number()
- Les entrées de type
checkbox
peuvent être validées à l’aide dez.boolean()
- Les entrées de type
file
peuvent être validées à l’aide dez.instanceof(File)
- Plusieurs entrées du même nom (
name
) peuvent être validées à l’aide dez.array(/* validateur */)
- Toutes les autres entrées peuvent être validées à l’aide de
z.string()
Les fonctions d’extension, notamment .refine()
, .transform()
et .pipe()
, sont également prises en charge sur cet objet. Les validateurs suivants sont pris en charge pour les champs de données de formulaire :
Pour appliquer une union de différents validateurs, utilisez le wrapper z.discriminatedUnion()
pour affiner le type en fonction d’un champ de formulaire spécifique. Cet exemple accepte une soumission de formulaire pour créer (create
) ou mettre à jour (update
) un utilisateur, en utilisant le champ de formulaire avec le nom type
pour déterminer l’objet à valider :
isInputError()
Titre de la section isInputError()Type : (error?: unknown | ActionError) => boolean
astro@4.15.0
L’utilitaire isInputError()
permet de vérifier si une ActionError
est une erreur de validation d’entrée. Lorsque le validateur utilisé pour input
correspond à z.object()
, les erreurs d’entrée incluent un objet fields
avec des messages d’erreur regroupés par nom.
isInputError()
.
ActionError
Titre de la section ActionError
Ajouté à la version :
astro@4.15.0
Le constructeur ActionError()
est utilisé pour créer des erreurs générées par un gestionnaire d’action (handler
). Il accepte une propriété code
décrivant l’erreur qui s’est produite (par exemple : "UNAUTHORIZED"
), et une propriété facultative message
contenant plus de détails.
Ajouté à la version :
astro@4.15.0
La propriété code
accepte les versions lisibles par l’homme de tous les codes d’état HTTP. Les codes suivants sont pris en charge :
BAD_REQUEST
(400) : Le client a envoyé une entrée non valide. Cette erreur est générée lorsqu’un validateur d’entrée d’action (input
) ne parvient pas à valider.UNAUTHORIZED
(401) : Le client ne dispose pas d’informations d’authentification valides.FORBIDDEN
(403) : Le client n’est pas autorisé à accéder à une ressource.NOT_FOUND
(404) : Le serveur ne trouve pas la ressource demandée.METHOD_NOT_SUPPORTED
(405) : Le serveur ne prend pas en charge la méthode demandée.TIMEOUT
(408) : Le serveur a expiré lors du traitement de la demande.CONFLICT
(409) : Le serveur ne peut pas mettre à jour une ressource en raison d’un conflit.PRECONDITION_FAILED
(412) : Le serveur ne répond pas à une condition préalable de la requête.PAYLOAD_TOO_LARGE
(413) : Le serveur ne peut pas traiter la demande car la charge utile est trop importante.UNSUPPORTED_MEDIA_TYPE
(415) : Le serveur ne prend pas en charge le type de média de la requête. Remarque : les actions vérifient déjà l’en-têteContent-Type
pour les requêtes JSON et de formulaire. Vous n’aurez donc probablement pas besoin de générer ce code manuellement.UNPROCESSABLE_CONTENT
(422) : Le serveur ne peut pas traiter la demande en raison d’erreurs sémantiques.TOO_MANY_REQUESTS
(429) : Le serveur a dépassé une limite de débit spécifiée.CLIENT_CLOSED_REQUEST
(499) : Le client a fermé la demande avant que le serveur puisse répondre.INTERNAL_SERVER_ERROR
(500) : Le serveur est tombé en panne de manière inattendue.NOT_IMPLEMENTED
(501) : Le serveur ne prend pas en charge la fonctionnalité demandée.BAD_GATEWAY
(502) : Le serveur a reçu une réponse non valide d’un serveur en amont.SERVICE_UNAVAILABLE
(503) : Le serveur est temporairement indisponible.GATEWAY_TIMEOUT
(504) : Le serveur a reçu un délai d’attente d’un serveur en amont.
message
Titre de la section message
Ajouté à la version :
astro@4.15.0
La propriété message
accepte une chaîne de caractères. (par exemple, « L’utilisateur doit être connecté. »)