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

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

defineAction()

Type : ({ accept, input, handler }) => ActionClient

Un utilitaire permettant de définir de nouvelles actions dans le 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()

Type : (input: TInputSchema, context: ActionAPIContext) => TOutput | Promise<TOutput>

Une fonction requise contenant la logique du serveur à exécuter lorsque l’action est appelée. Les données renvoyées par handler() sont automatiquement sérialisées et envoyées à l’appelant.

Le gestionnaire (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 second argument est un sous-ensemble de l’objet context d’Astro.

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)

Type : ZodType | undefined

Une propriété facultative qui accepte un validateur Zod (par exemple, un objet Zod, une union discriminée Zod) pour valider les entrées du gestionnaire lors de l’exécution. Si la validation de l’action échoue, une erreur BAD_REQUEST est renvoyée et le gestionnaire (handler) n’est pas appelé.

Si input est omis, le gestionnaire (handler) recevra une entrée de type unknown pour les requêtes JSON et de type FormData pour les requêtes de formulaire.

Propriété accept

Type : "form" | "json"
Par défaut : json

Définit le format attendu par une action :

• Utilisez form lorsque votre action accepte des données de formulaire (FormData).
• Utilisez json, la valeur par défaut, pour tous les autres cas.

Lorsque votre action accepte des champs de formulaire, le validateur z.object() analysera automatiquement FormData en un objet typé. Tous les validateurs Zod sont pris en charge pour valider vos champs.

Découvrez comment utiliser des validateurs avec les champs de formulaire dans le guide des actions. Celui-ci comprend des exemples d’utilisation et des informations sur la gestion spéciale des champs.

actions

Type : Record<string, ActionClient>

Un objet contenant toutes vos actions avec le nom de l’action comme nom de propriété associé à une fonction pour appeler cette action.

src/pages/index.astro

---
---

<script>
import { actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
}
</script>

Pour qu’Astro reconnaisse cette propriété, vous devrez peut-être redémarrer le serveur de développement ou exécuter la commande astro sync (s + enter).

isInputError()

Type : (error?: unknown) => boolean

Un utilitaire utilisé pour 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()

Type : (error?: unknown) => boolean

Un utilitaire pour vérifier si votre action a généré une erreur ActionError dans la propriété du gestionnaire. Ceci est utile pour affiner le type d’une erreur générique.

src/pages/index.astro

---
---

<script>
import { isActionError, actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (isActionError(error)) {
    // Gérer les erreurs spécifiques à l'action
    console.log(error.code);
  }
}
</script>

ActionError

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.

L’exemple suivant crée une nouvelle erreur ActionError lorsque l’utilisateur n’est pas connecté :

src/actions/index.ts

import { defineAction, ActionError } from "astro:actions";

export const server = {
  getUserOrThrow: defineAction({
    accept: 'form',
    handler: async (_, { locals }) => {
      if (locals.user?.name !== 'florian') {
        throw new ActionError({
          code: 'UNAUTHORIZED',
          message: 'Non connecté',
        });
      }
      return locals.user;
    },
  }),
}

Vous pouvez également utiliser ActionError pour affiner le type d’erreur lors de la gestion des résultats d’une action :

src/pages/index.astro

---
---

<script>
import { ActionError, actions } from 'astro:actions';

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (error instanceof ActionError) {
    // Gérer les erreurs spécifiques à l'action
    console.log(error.code);
  }
}
</script>

code

Type : ActionErrorCode

Définit une version lisible par l’homme d’un code d’état HTTP.

message

Type : string

Une propriété facultative pour décrire l’erreur (par exemple « L’utilisateur doit être connecté »).

stack

Type : string

Une propriété facultative pour transmettre la trace d’appels (ou « stack trace » en anglais).

getActionContext()

Type : (context: APIContext) => AstroActionContext

Ajouté à la version : astro@5.0.0

Une fonction appelée depuis votre gestionnaire middleware pour récupérer des informations sur les requêtes d’action entrantes. Elle renvoie un objet action contenant des informations sur la requête, une méthode deserializeActionResult() et les fonctions setActionResult() et serializeActionResult() pour définir par programmation la valeur renvoyée par Astro.getActionResult().

getActionContext() vous permet d’obtenir et de définir par programmation les résultats d’actions à l’aide d’un middleware, vous permettant de conserver les résultats d’actions à partir de formulaires HTML, de bloquer les demandes d’actions avec des contrôles de sécurité supplémentaires, et bien plus encore.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});

action

Type : { calledFrom: “rpc” | “form”; name: string; handler: () => Promise<SafeResult>; } | undefined

Un objet contenant des informations sur une requête d’action entrante. Il est disponible via getActionContext() et fournit le nom de l’action (name), son gestionnaire (handler) et indique si l’action a été appelée à partir d’une fonction RPC côté client (par exemple actions.newsletter()) ou d’une action de formulaire HTML.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'rpc' && action.name.startsWith('private')) {
    // Rechercher un jeton de session valide
  }
  // ...
});

calledFrom

Type : "rpc" | "form"

Détermine si une action a été appelée à l’aide d’une fonction RPC ou d’une action de formulaire HTML.

name

Type : string

Le nom de l’action. Utile pour suivre la source du résultat d’une action lors d’une redirection.

handler()

Type : () => Promise<SafeResult>

Une méthode permettant d’appeler par programmation une action pour obtenir le résultat.

setActionResult()

Type : (actionName: string, actionResult: SerializedActionResult) => void

Une fonction permettant de définir par programmation la valeur renvoyée par Astro.getActionResult() dans le middleware. Le nom de l’action et un résultat d’action sérialisé par serializeActionResult() lui sont transmis. L’appel de cette fonction depuis le middleware désactivera la gestion des résultats d’action d’Astro.

Ceci est utile lors de l’appel d’actions à partir d’un formulaire HTML pour conserver et charger les résultats d’une session.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';
export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    // ... gérer le résultat de l'action
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});

Consultez le guide des sessions avancées pour un exemple d’implémentation à l’aide de Netlify Blob.

serializeActionResult()

Type : (res: SafeResult) => SerializedActionResult

Sérialise le résultat d’une action au format JSON pour la persistance. Cela est nécessaire pour gérer correctement les valeurs de retour non JSON telles que Map ou Date, ainsi que l’objet ActionError.

Appelez cette fonction lors de la sérialisation d’un résultat d’action à transmettre à setActionResult() :

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action) {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  // ...
});

deserializeActionResult()

Type : (res: SerializedActionResult) => SafeResult

Inverse l’effet de serializeActionResult() et rétablit le résultat d’une action à son état d’origine. Ceci est utile pour accéder aux objets data et error d’un résultat d’action sérialisé.

getActionPath()

Type : (action: ActionClient) => string

Ajouté à la version : astro@5.1.0

Un utilitaire qui accepte une action et renvoie un chemin d’URL afin que vous puissiez exécuter un appel d’action en tant qu’opération fetch() directement. Cela vous permet de fournir des détails tels que des en-têtes personnalisés lorsque vous appelez votre action. Ensuite, vous pouvez gérer les données renvoyées au format personnalisé selon vos besoins, comme si vous aviez appelé une action directement.

Cet exemple montre comment appeler une action like définie en passant l’en-tête Authorization et l’option keepalive :

src/components/my-component.astro

<script>
import { actions, getActionPath } from 'astro:actions'

await fetch(getActionPath(actions.like), {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({ id: 'YOUR_ID' }),
  keepalive: true
})
</script>

Cet exemple montre comment appeler la même action like en utilisant l’API sendBeacon :

src/components/my-component.astro

<script>
import { actions, getActionPath } from 'astro:actions'

navigator.sendBeacon(
  getActionPath(actions.like),
  new Blob([JSON.stringify({ id: 'YOUR_ID' })], {
    type: 'application/json'
  })
)
</script>

ACTION_QUERY_PARAMS

Type : { actionName: string, actionPayload: string }

Un objet contenant les noms des paramètres de requête utilisés en interne par Astro lors de la gestion des soumissions d’actions de formulaire.

Lorsque vous soumettez un formulaire via une action, les paramètres de requête suivants sont ajoutés à l’URL pour suivre l’appel de l’action :

• actionName - Le paramètre de requête contenant le nom de l’action appelée
• actionPayload - Le paramètre de requête contenant les données sérialisées du formulaire

Cette constante peut être utile lorsque vous devez nettoyer les URL après la soumission d’un formulaire. Par exemple, vous pourriez vouloir supprimer des paramètres de requête liés à une action lors d’une redirection :

src/pages/api/contact.ts

import type { APIRoute } from "astro";
import { ACTION_QUERY_PARAMS } from 'astro:actions'

export const GET: APIRoute = ({ params, request }) => {
  const link = request.url.searchParams;
  link.delete(ACTION_QUERY_PARAMS.actionName);
  link.delete(ACTION_QUERY_PARAMS.actionPayload);

  return redirect(link, 303);
};

Types d’astro:actions

import type {
  ActionAPIContext,
  ActionClient,
  ActionErrorCode,
  ActionReturnType,
  SafeResult,
 } from 'astro:actions';

ActionAPIContext

Un sous-ensemble de l’objet de contexte Astro. Les propriétés suivantes ne sont pas disponibles : callAction, getActionResult, props et redirect.

ActionClient

Types :

• (input?: any) => Promise<SafeResult>
• { queryString?: string; orThrow: (input?: any) => Promise<Awaited<TOutput>>; }

Représente une action à exécuter sur le client. Vous pouvez l’utiliser comme une fonction qui accepte les données d’entrée et renvoie une promesse avec un objet SafeResult contenant le résultat de l’action ou les erreurs de validation.

L’exemple suivant montre comment vous pouvez fournir une gestion des erreurs avec une instruction if lorsque l’incrémentation du nombre de mentions « J’aime » échoue :

src/pages/articles/article-1.astro

---
---

<!-- votre modèle -->

<script>
import { actions } from 'astro:actions';

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const { data: updatedLikes, error } = await actions.likePost({ postId: post?.id });
  if (error) {
    /* gérer les erreurs */
  }
})
</script>

À la place, vous pouvez l’utiliser comme un objet vous donnant accès à queryString et à une méthode alternative orThrow().

Propriété queryString

Type : string

Une chaîne de caractères représentant l’action, permettant de créer des URL d’action de formulaire. Ceci peut être utile lorsque votre composant de formulaire est utilisé à plusieurs endroits, mais que vous devez rediriger vers une URL différente lors de l’envoi.

L’exemple suivant utilise queryString pour créer une URL qui sera transmise à l’attribut action du formulaire via une propriété personnalisée :

src/pages/postal-service.astro

---
import { actions } from 'astro:actions';
import FeedbackForm from "../components/FeedbackForm.astro";

const feedbackUrl = new URL('/feedback', Astro.url);
feedbackUrl.search = actions.myAction.queryString;
---
<FeedbackForm sendTo={feedbackUrl.pathname} />

Propriété orThrow()

Type : (input?: any) => Promise<Awaited<TOutput>>

Une méthode qui génère une erreur en cas d’échec au lieu de renvoyer les erreurs. Ceci est utile lorsque vous souhaitez des exceptions plutôt qu’une gestion manuelle des erreurs.

L’exemple suivant utilise orThrow() pour ignorer la gestion des erreurs lorsque l’incrémentation du nombre de mentions « J’aime » échoue :

src/pages/articles/article-1.astro

---
---

<!-- votre modèle -->

<script>
import { actions } from 'astro:actions';

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const updatedLikes = await actions.likePost.orThrow({ postId: post?.id });
})
</script>

ActionErrorCode

Type : string

Un type d’union de codes d’état HTTP standard définis par l’IANA utilisant les versions lisibles par l’homme sous forme de chaînes de caractères en majuscules séparées par un trait de soulignement (par exemple BAD_REQUEST ou PAYLOAD_TOO_LARGE).

ActionReturnType

Type : Awaited<ReturnType<ActionHandler>>

Un type utilitaire qui extrait le type du résultat d’un gestionnaire d’actions. Cela donne accès à la fois l’objet Promise (si le gestionnaire est asynchrone) et le ReturnType pour vous donner le type du résultat réel. Cela peut être utile si vous devez utiliser le type du résultat d’une action dans vos propres définitions de type.

L’exemple suivant utilise ActionReturnType pour récupérer le type du résultat attendu pour une action nommée contact :

src/components/Form.astro

---
import { actions, ActionReturnType } from 'astro:actions';

type ContactResult = ActionReturnType<typeof actions.contact>;
---

SafeResult

Type : { data: TOutput, error: undefined } | { data: undefined, error: ActionError }

Représente le résultat d’un appel d’action :

• en cas de succès, data contient le résultat de l’action et error est indéfini (undefined).
• En cas d’échec, error contient une erreur ActionError avec des erreurs de validation ou d’exécution, et data est indéfini (undefined).