diff --git a/src/content/docs/fr/reference/image-service-reference.mdx b/src/content/docs/fr/reference/image-service-reference.mdx index ba303a86a4930..c583f43b58305 100644 --- a/src/content/docs/fr/reference/image-service-reference.mdx +++ b/src/content/docs/fr/reference/image-service-reference.mdx @@ -31,21 +31,21 @@ Un service externe pointe vers une URL distante à utiliser comme attribut `src` import type { ExternalImageService, ImageTransform, AstroConfig } from "astro"; const service: ExternalImageService = { - validateOptions(options: ImageTransform, imageConfig: AstroConfig['image']) { + validateOptions(options: ImageTransform, imageConfig: AstroConfig['image'], logger) { const serviceConfig = imageConfig.service.config; // Appliquer la largeur maximale définie par l'utilisateur. if (options.width && options.width > serviceConfig.maxWidth) { - console.warn(`La largeur de l'image ${options.width} dépasse la largeur maximale ${serviceConfig.maxWidth}. Repli sur la largeur maximale.`); + logger.warn(`La largeur de l'image ${options.width} dépasse la largeur maximale ${serviceConfig.maxWidth}. Repli sur la largeur maximale.`); options.width = serviceConfig.maxWidth; } return options; }, - getURL(options, imageConfig) { + getURL(options, imageConfig, logger) { return `https://monsupercdn.com/${options.src}?q=${options.quality}&w=${options.width}&h=${options.height}`; }, - getHTMLAttributes(options, imageConfig) { + getHTMLAttributes(options, imageConfig, logger) { const { src, format, quality, ...attributes } = options; return { ...attributes, @@ -68,7 +68,7 @@ import type { ImageTransform, LocalImageService, AstroConfig } from "astro"; import { mySuperLibraryThatEncodesImages } from "@example/ma-super-bibliotheque"; const service: LocalImageService = { - getURL(options: ImageTransform, imageConfig) { + getURL(options: ImageTransform, imageConfig, logger) { const searchParams = new URLSearchParams(); searchParams.append('href', typeof options.src === "string" ? options.src : options.src.src); options.width && searchParams.append('w', options.width.toString()); @@ -79,7 +79,7 @@ const service: LocalImageService = { // Ou utilisez le point de terminaison intégré, qui appellera vos fonctions parseURL et transform : // return `/_image?${searchParams}`; }, - parseURL(url: URL, imageConfig) { + parseURL(url: URL, imageConfig, logger) { const params = url.searchParams; return { src: params.get('href')!, @@ -89,14 +89,14 @@ const service: LocalImageService = { quality: params.get('q'), }; }, - async transform(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig) { + async transform(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig, logger) { const { buffer } = await mySuperLibraryThatEncodesImages(options); return { data: buffer, format: options.format, }; }, - getHTMLAttributes(options, imageConfig) { + getHTMLAttributes(options, imageConfig, logger) { let targetWidth = options.width; let targetHeight = options.height; if (typeof options.src === "object") { @@ -141,7 +141,7 @@ import { getConfiguredImageService, imageConfig } from "astro:assets"; import * as mime from "mrmime"; import { getImageBuffer } from "./mon-recuperateur-d-images-personnalise.js"; -export const GET: APIRoute = async ({ request }) => { +export const GET: APIRoute = async ({ request, logger }) => { const imageService = await getConfiguredImageService(); if (!isLocalService(imageService)) { @@ -154,6 +154,7 @@ export const GET: APIRoute = async ({ request }) => { const imageTransform = await imageService.parseURL( new URL(request.url), imageConfig, + logger, ); if (!imageTransform) { @@ -166,6 +167,7 @@ export const GET: APIRoute = async ({ request }) => { inputBuffer, imageTransform, imageConfig, + logger, ); return new Response(new Uint8Array(data), { status: 200, @@ -185,7 +187,7 @@ export const GET: APIRoute = async ({ request }) => {

-**Type :** (options: ImageTransform, imageConfig: AstroConfig['image']) => string | Promise\
+**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => string | Promise\

@@ -195,57 +197,71 @@ Pour les services locaux, ce hook renvoie l'URL du point de terminaison qui gén Pour les services externes, ce hook renvoie l'URL finale de l'image. -Pour les deux types de services, les `options` sont les propriétés passées par l'utilisateur comme attributs du composant `` ou comme options de `getImage()`. +Pour les deux types de services, les `options` sont les propriétés passées par l'utilisateur comme attributs du composant `` ou comme options de `getImage()`. Ce hook reçoit également la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. ### `parseURL()`

-**Type :** (url: URL, imageConfig: AstroConfig['image']) => \{ src: string, [key: string]: any \} | undefined | Promise\<\{ src: string, [key: string]: any \}\> | Promise\
+**Type :** (url: URL, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => \{ src: string, [key: string]: any \} | undefined | Promise\<\{ src: string, [key: string]: any \}\> | Promise\

**Requis pour les services locaux uniquement ; indisponible pour les services externes** -Ce hook analyse les URLs générées par `getURL()` en un objet avec les différentes propriétés à utiliser par `transform` (en SSR et en mode dev). Il n'est pas utilisé pendant la compilation. +Ce hook analyse les URLs générées par `getURL()` pour les transformer en un objet contenant les différentes propriétés à utiliser par `transform`. Il reçoit trois paramètres : l'URL à analyser, la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. + +Ce hook est utilisé uniquement pour le rendu à la demande et en mode développement. Il n'est pas utilisé pendant la compilation. ### `transform()`

-**Type :** (inputBuffer: Uint8Array, options: \{ src: string, [key: string]: any \}, imageConfig: AstroConfig['image']) => Promise\<\{ data: Uint8Array; format: ImageOutputFormat \}\>
+**Type :** (inputBuffer: Uint8Array, options: \{ src: string, [key: string]: any \}, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => Promise\<\{ data: Uint8Array; format: ImageOutputFormat \}\>

**Requis pour les services locaux uniquement ; indisponible pour les services externes** -Ce hook transforme et renvoie l'image et est appelé pendant la compilation pour créer les fichiers de ressources finaux. +Ce hook transforme et renvoie l'image et est appelé pendant la compilation pour créer les fichiers de ressources finaux. Il reçoit quatre paramètres : l'image d'entrée, un objet d'options, la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. Vous devez renvoyer un `format` pour garantir que le type MIME approprié est fourni aux utilisateurs pour le rendu à la demande et le mode de développement. +```ts +import type { LocalImageService } from 'astro'; + +const service: LocalImageService = { + // ... + async transform(inputBuffer, transform, imageConfig, logger) { + logger.warn(`Impossible d'optimiser « ${transform.src} ». Transmission sans modification.`); + return { data: inputBuffer, format: 'png' }; + }, +}; +``` + ### `getHTMLAttributes()`

-**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'] ) => Record\ | Promise\\>
+**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => Record\ | Promise\\>

**Facultatif pour les services locaux et externes** -Ce hook renvoie tous les attributs supplémentaires utilisés pour restituer l'image en HTML, en fonction des paramètres transmis par l'utilisateur (`options`). +Ce hook renvoie tous les attributs supplémentaires utilisés pour restituer l'image en HTML, en fonction des paramètres transmis par l'utilisateur (`options`). Il reçoit également la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. ### `getSrcSet()`

-**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'] ) => UnresolvedSrcSetValue[] | Promise\
+**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => UnresolvedSrcSetValue[] | Promise\

**Facultatif pour les services locaux et externes** -Ce hook génère plusieurs variantes de l'image spécifiée, par exemple, pour générer un attribut `srcset` sur une `` ou `source` sur ``. +Ce hook génère plusieurs variantes de l'image spécifiée, par exemple, pour générer un attribut `srcset` sur une `` ou `source` sur ``. Il reçoit trois paramètres : un objet d'options, la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. Ce hook retourne un tableau d'objets avec les propriétés suivantes : @@ -261,13 +277,13 @@ export type UnresolvedSrcSetValue = {

-**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'] ) => ImageTransform | Promise\ +**Type :** (options: ImageTransform, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => ImageTransform | Promise\

**Facultatif pour les services locaux et externes** -Ce hook vous permet de valider et d'augmenter les options passées par l'utilisateur. C'est utile pour définir des options par défaut, ou pour indiquer à l'utilisateur qu'un paramètre est nécessaire. +Ce hook vous permet de valider et d'augmenter les options passées par l'utilisateur. C'est utile pour définir des options par défaut, ou pour indiquer à l'utilisateur qu'un paramètre est nécessaire. Il reçoit également la configuration de l'image et, depuis Astro v7.3.0, un journaliseur que vous pouvez utiliser pour avertir l'utilisateur des options invalides. [Voir comment `validateOptions()` est utilisé dans les services intégrés d'Astro](https://github.com/withastro/astro/blob/0ab6bad7dffd413c975ab00e545f8bc150f6a92f/packages/astro/src/assets/services/service.ts#L124). @@ -275,13 +291,13 @@ Ce hook vous permet de valider et d'augmenter les options passées par l'utilisa

-**Type :** (url: string, imageConfig: AstroConfig['image'] ) => Omit\<ImageMetadata, 'src' | 'fsPath'\> | Promise\ImageMetadata, 'src' | 'fsPath'\>\> +**Type :** (url: string, imageConfig: AstroConfig['image'], logger: AstroRuntimeLogger) => Omit\<ImageMetadata, 'src' | 'fsPath'\> | Promise\ImageMetadata, 'src' | 'fsPath'\>\>

**Facultatif pour les services locaux et externes** -Ce hook vous permet d'étendre le comportement de [`inferRemoteSize()`](/fr/reference/modules/astro-assets/#inferremotesize). Ceci est utile pour réduire le trafic réseau en mettant les images en cache, ou lorsque vous pouvez prédire les informations d'une image à partir de son URL. +Ce hook vous permet d'étendre le comportement de [`inferRemoteSize()`](/fr/reference/modules/astro-assets/#inferremotesize). Ceci est utile pour réduire le trafic réseau en mettant les images en cache, ou lorsque vous pouvez prédire les informations d'une image à partir de son URL. Il reçoit trois paramètres : l'URL de l'image, la configuration de l'image et, depuis Astro v7.3.0, un journaliseur. ## Configuration de l'utilisateur