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:actions

import {
  actions,
  defineAction,
  isInputError,
  isActionError,
  ActionError,
 } from 'astro:actions';

defineAction()

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.

src/actions/index.ts

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  getGreeting: defineAction({
    input: z.object({
      name: z.string(),
    }),
    handler: async (input, context) => {
      return `Bonjour, ${input.name}!`
    }
  })
}

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 de z.number()
• Les entrées de type checkbox peuvent être validées à l’aide de z.boolean()
• Les entrées de type file peuvent être validées à l’aide de z.instanceof(File)
• Plusieurs entrées du même nom (name) peuvent être validées à l’aide de z.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 :

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  changeUser: defineAction({
    accept: 'form',
    input: z.discriminatedUnion('type', [
      z.object({
        // Correspond lorsque le champ `type` est défini sur la valeur `create`
        type: z.literal('create'),
        name: z.string(),
        email: z.string().email(),
      }),
      z.object({
        // Correspond lorsque le champ `type` est défini sur la valeur `update`
        type: z.literal('update'),
        id: z.number(),
        name: z.string(),
        email: z.string().email(),
      }),
    ]),
    async handler(input) {
      if (input.type === 'create') {
        // l'entrée correspond à { type: 'create', name: string, email: string }
      } else {
        // l'entrée correspond à { type: 'update', id: number, name: string, email: string }
      }
    },
  }),
};

isInputError()

Titre de la section isInputError()

Type : (error?: unknown | ActionError) => boolean

Ajouté à la version : 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.

Consultez le guide des erreurs de saisie de formulaire pour en savoir plus sur l’utilisation de isInputError().

isActionError()

Titre de la section isActionError()

Type : (error?: unknown | ActionError) => boolean

Ajouté à la version : astro@4.15.0

La fonction isActionError() est utilisée pour vérifier si votre action a déclenché une ActionError dans la propriété du gestionnaire. Ceci est utile pour restreindre le type d’une erreur générique dans un bloc try / catch.

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.

code

Titre de la section code

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ête Content-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é. »)