From b0d3c3375419662242252a6750a2b4c878990f1e Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Sat, 26 Oct 2024 12:35:46 +0200 Subject: [PATCH] i18n(fr): create `reference/modules/astro-actions.mdx` See #9687 and #9819 --- .../fr/reference/modules/astro-actions.mdx | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 src/content/docs/fr/reference/modules/astro-actions.mdx diff --git a/src/content/docs/fr/reference/modules/astro-actions.mdx b/src/content/docs/fr/reference/modules/astro-actions.mdx new file mode 100644 index 0000000000000..1ef57e4583696 --- /dev/null +++ b/src/content/docs/fr/reference/modules/astro-actions.mdx @@ -0,0 +1,176 @@ +--- +title: Référence de l'API Actions +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +

+ +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](/fr/guides/actions/). + +## Importations depuis `astro:actions` + +```js +import { + actions, + defineAction, + isInputError, + ActionError, + } from 'astro:actions'; +``` + +### `defineAction()` + +

+ +

+ +L'utilitaire `defineAction()` est utilisé pour définir de nouvelles actions à partir du fichier `src/actions/index.ts`. Il accepte une fonction [`handler()`](#propriété-handler) contenant la logique du serveur à exécuter et une propriété facultative [`input`](#validateur-de-saisie-input) pour valider les paramètres d'entrée lors de l'exécution. + +```ts title="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, 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`](#validateur-de-saisie-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](/fr/reference/api-reference/#contexte-du-point-de-terminaison) d'Astro, à l'exception de `getActionResult()`, `callAction()` et `redirect()`. + +Les valeurs de retour sont analysées à l'aide de la [bibliothèque devalue](https://github.com/Rich-Harris/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` +

+ +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`](#actionerror) 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'` + +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 : + +```ts +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()` + +

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

+ +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](/fr/guides/actions/#affichage-des-erreurs-de-saisie-du-formulaire) pour en savoir plus sur l'utilisation de `isInputError()`. + +### `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. + +#### `code` + +

+ +

+ +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`](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/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` + +

+ +

+ +La propriété `message` accepte une chaîne de caractères. (par exemple, « L'utilisateur doit être connecté. »)