Référence de l'API des images et des ressources

Ajouté à la version : astro@3.0.0

Astro fournit des composants intégrés et des fonctions d’aide pour optimiser et afficher vos images. Pour des fonctionnalités et des exemples d’utilisation, consultez notre guide sur les images.

Importations depuis astro:assets

Les utilitaires suivants sont importés depuis le module virtuel des ressources :

import {
  Image,
  Picture,
  Font,
  getImage,
  inferRemoteSize,
  getConfiguredImageService,
  imageConfig,
  fontData,
} from 'astro:assets';

<Image />

Le composant <Image /> optimise et transforme les images.

src/components/MonComposant.astro

---
// importe le composant Image et l'image
import { Image } from 'astro:assets';
import monImage from "../assets/mon_image.png"; // Image a une résolution de 1600x900
---

<!-- `alt` est obligatoire sur le composant Image -->
<Image src={monImage} alt="Une description de mon image." />

<!-- Sortie -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/mon_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Une description de mon image."
/>

Le composant <Image /> accepte les propriétés listées ci-dessous en plus de toutes les propriétés acceptées par la balise HTML <img>.

src (obligatoire)

Type : ImageMetadata | string | Promise<{ default: ImageMetadata }>

Le format de la valeur src de votre fichier image dépend de l’emplacement de votre fichier image :

• Images locales dans src/ - vous devez également importer l’image en utilisant un chemin de fichier relatif ou configurer et utiliser un alias d’importation. Utilisez ensuite le nom de l’importation comme valeur dans src :

  src/pages/index.astro

  ---
  import { Image } from 'astro:assets';
  import monImageImportee from '../assets/mon-image-locale.png';
  ---
  <Image src={monImageImportee} alt="texte descriptif" />

• Images dans le dossier public/ - utilisez le chemin d’accès au fichier de l’image par rapport au dossier public :

  src/pages/index.astro

  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/images/mon-image-publique.png"
    alt="texte descriptif"
    width="200"
    height="150"
  />

• Images distantes - utilisez l’URL complète de l’image comme valeur de propriété :

  src/pages/index.astro

  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://example.com/image-distante.jpg"
    alt="texte descriptif"
    width="200"
    height="150"
  />

alt (obligatoire)

Type : string

Utilisez l’attribut alt requis pour fournir un texte alternatif descriptif pour les images.

Si une image est simplement décorative (c’est-à-dire qu’elle ne contribue pas à la compréhension de la page), définissez alt="" pour que les lecteurs d’écran et autres technologies d’assistance sachent qu’il faut ignorer l’image.

width et height (obligatoires pour les images dans public/)

Type : number | `${number}` | undefined

Ces propriétés définissent les dimensions à utiliser pour l’image.

Lorsqu’un type de mise en page (layout) est défini, celles-ci sont automatiquement générées en fonction des dimensions de l’image et, dans la plupart des cas, ne doivent pas être définis manuellement.

Lorsque vous utilisez des images dans leur rapport hauteur/largeur d’origine, width et height sont facultatives. Ces dimensions peuvent être automatiquement déduites des fichiers image situés dans src/. Pour les images distantes, ajoutez l’attribut inferSize défini sur true sur les composants <Image /> ou <Picture /> ou utilisez la fonction inferRemoteSize().

Cependant, ces deux propriétés sont requises pour les images stockées dans votre dossier public/ car Astro n’est pas en mesure d’analyser ces fichiers.

densities

Type : (number | `${number}x`)[] | undefined

Ajouté à la version : astro@3.3.0

Une liste de densités de pixels à générer pour l’image.

L’attribut densities n’est pas compatible avec l’utilisation de la propriété layout ou du paramètre de configuration image.layout, et sera ignoré s’il est défini.

Si elle est fournie, cette valeur sera utilisée pour générer un attribut srcset sur la balise <img>. Ne fournissez pas de valeur pour widths lorsque vous utilisez cette valeur.

Les densités égales à des largeurs supérieures à celles de l’image d’origine seront ignorées pour éviter de mettre à l’échelle l’image.

src/components/MonComposant.astro

---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image
  src={monImage}
  width={monImage.width / 2}
  densities={[1.5, 2]}
  alt="Une description de mon image."
/>

<!-- Sortie -->
<img
  src="/_astro/mon_image.hash.webp"
  srcset="
    /_astro/mon_image.hash.webp 1.5x
    /_astro/mon_image.hash.webp 2x
  "
  alt="Une description de mon image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

widths

Type : number[] | undefined

Ajouté à la version : astro@3.3.0

Une liste de largeurs à générer pour l’image.

Si elle est fournie, cette valeur sera utilisée pour générer un attribut srcset sur la balise <img>. Une propriété sizes doit également être fournie.

Les attributs widths et sizes seront automatiquement générés pour les images utilisant une propriété layout. Fournir ces valeurs n’est généralement pas nécessaire, mais elles peuvent servir à remplacer les valeurs générées automatiquement.

Ne fournissez pas de valeur pour densities lorsque vous utilisez cette valeur. Une seule de ces deux valeurs peut être utilisée pour générer un srcset.

Les largeurs supérieures à l’image d’origine seront ignorées pour éviter de mettre à l’échelle l’image.

src/components/MonComposant.astro

---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png'; // La résolution de l'image est de 1600x900
---
<Image
  src={monImage}
  widths={[240, 540, 720, monImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${monImage.width}px`}
  alt="Une description de mon image."
/>

<!-- Sortie -->
<img
  src="/_astro/mon_image.hash.webp"
  srcset="
    /_astro/mon_image.hash.webp 240w,
    /_astro/mon_image.hash.webp 540w,
    /_astro/mon_image.hash.webp 720w,
    /_astro/mon_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Une description de mon image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>

sizes

Type : string | undefined

Ajouté à la version : astro@3.3.0

Spécifie la largeur de la mise en page de l’image pour chaque valeur d’une liste de conditions de média. Doit être fourni lors de la spécification de largeurs (widths).

Les attributs widths et sizes seront automatiquement générés pour les images utilisant une propriété layout. Fournir ces valeurs n’est généralement pas nécessaire, mais elles peuvent servir à remplacer les valeurs générées automatiquement.

L’attribut sizes généré pour les images contraintes (constrained) et pleine largeur (full-width) suppose que l’image s’affiche presque sur toute la largeur de l’écran lorsque la fenêtre d’affichage est plus petite que la largeur de l’image. Si la différence est significative (par exemple, si l’image est affichée sur plusieurs colonnes sur un petit écran), vous devrez peut-être ajuster manuellement l’attribut sizes pour obtenir de meilleurs résultats.

format

Type : ImageOutputFormat | undefined

Vous pouvez éventuellement indiquer le type de fichier image de sortie à utiliser.

Par défaut, le composant <Image /> produira un fichier .webp.

quality

Type : ImageQuality | undefined

quality est une propriété facultative qui peut être :

• un préréglage (low, mid, high, max) qui est automatiquement normalisé entre les formats.
• un nombre compris entre 0 et 100 (interprété différemment selon les formats).

inferSize

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.4.0

Vous permet de définir automatiquement la largeur (width) et la hauteur (height) d’origine d’une image distante.

Par défaut, cette valeur est définie sur false et vous devez spécifier manuellement les deux dimensions de votre image distante.

Ajoutez inferSize au composant <Image /> (ou inferSize: true à getImage()) pour déduire ces valeurs du contenu de l’image lors de la récupération. Cela est utile si vous ne connaissez pas les dimensions de l’image distante ou si elles peuvent changer :

src/components/MonComposant.astro

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Un chat qui dort au soleil." />

À partir d’Astro 5.17.3, inferSize ne récupère les dimensions que pour les domaines d’images distants autorisés. Les images distantes ne figurant pas sur la liste blanche ne sont pas récupérées.

priority

Type : boolean
Par défaut : false

Ajouté à la version : astro@5.10.0

Vous permet de définir automatiquement les attributs loading, decoding et fetchpriority sur leurs valeurs optimales pour les images au-dessus de la ligne de flottaison.

src/components/MonComposant.astro

---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} priority alt="Une description de mon image" />

Lorsque priority="true" (ou la syntaxe abrégée priority) est ajouté au composant <Image /> ou <Picture />, les attributs suivants sont ajoutés pour indiquer au navigateur de charger l’image immédiatement :

loading="eager"
decoding="sync"
fetchpriority="high"

Ces attributs individuels peuvent toujours être définis manuellement si vous devez les personnaliser davantage.

layout

Type : 'constrained' | 'full-width' | 'fixed' | 'none'
Par défaut : image.layout | 'none'

Ajouté à la version : astro@5.10.0

Détermine comment l’image doit être redimensionnée lorsque la taille de son conteneur change. Peut être utilisée pour remplacer la valeur configurée par défaut pour image.layout.

MonComposant.astro

---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} alt="Une description de mon image" layout='constrained' width={800} height={600} />

Lorsqu’une mise en page est définie, les attributs srcset et sizes sont générés automatiquement en fonction des dimensions de l’image et du type de mise en page. Le composant <Image /> précédent générera le code HTML suivant :

<img
  src="/_astro/mon_image.hash3.webp"
  srcset="/_astro/mon_image.hash1.webp 640w,
      /_astro/mon_image.hash2.webp 750w,
      /_astro/mon_image.hash3.webp 800w,
      /_astro/mon_image.hash4.webp 828w,
      /_astro/mon_image.hash5.webp 1080w,
      /_astro/mon_image.hash6.webp 1280w,
      /_astro/mon_image.hash7.webp 1600w"
  alt="Une description de mon image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

layout prend en charge les valeurs suivantes :

• constrained - L’image sera redimensionnée pour s’adapter au conteneur, en conservant son rapport hauteur/largeur, mais ne sera pas agrandie au-delà de la largeur et de la hauteur spécifiées, ni au-delà des dimensions originales de l’image.

  Utilisez cette option si vous souhaitez que l’image s’affiche à la taille demandée lorsque cela est possible, mais qu’elle soit redimensionnée pour s’adapter aux écrans plus petits. Cela correspond au comportement par défaut des images avec Tailwind. En cas de doute, il s’agit probablement de la mise en page que vous devriez choisir.

• full-width - L’image s’adaptera à la largeur du conteneur, en conservant ses proportions.

  Utilisez ceci pour les images de couverture ou les autres images qui doivent occuper toute la largeur de la page.

• fixed - L’image conservera les dimensions demandées et ne sera pas redimensionnée. Elle générera un srcset pour prendre en charge les écrans haute densité, mais pas pour les différentes tailles d’écran.

  Utilisez cette option si l’image ne sera pas redimensionnée, par exemple pour des icônes ou des logos plus petits que la largeur de l’écran, ou pour d’autres images dans un conteneur à largeur fixe.

• none - L’image ne sera pas adaptative. Aucun attribut srcset ni sizes ne sera généré automatiquement, et aucun style ne sera appliqué.

  Ceci est utile si vous avez activé une mise en page par défaut, mais que vous souhaitez la désactiver pour une image spécifique.

Par exemple, si la mise en page par défaut est définie sur constrained, vous pouvez remplacer la propriété layout de chaque image :

src/components/MonComposant.astro

---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} alt="Cela utilisera une mise en page contrainte" width={800} height={600} />
<Image src={monImage} alt="Cela utilisera une mise en page pleine largeur" layout="full-width" />
<Image src={monImage} alt="Cela désactivera les images adaptatives" layout="none" />

La valeur de layout définit également les styles par défaut appliqués à la balise <img> pour déterminer comment l’image doit être redimensionnée en fonction de son conteneur :

Styles des images adaptatives

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

fit

Type : 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
Par défaut : image.objectFit | 'cover'

Ajouté à la version : astro@5.10.0

Définit comment une image doit être recadrée si son rapport hauteur/largeur est modifié.

Les valeurs correspondent à celles de la propriété CSS object-fit. Par défaut, cover, ou la valeur de image.objectFit si elle est définie. Peut être utilisée pour remplacer les styles par défaut de object-fit.

position

Type : string
Par défaut : image.objectPosition | 'center'

Ajouté à la version : astro@5.10.0

Définit la position du recadrage d’une image si son rapport hauteur/largeur est modifié.

Les valeurs correspondent à celles de la propriété CSS object-position. Par défaut, la valeur est center, ou la valeur de image.objectPosition si elle est définie. Peut être utilisé pour remplacer les styles par défaut de object-position.

background

Type : string | undefined

Ajouté à la version : astro@5.17.0

La couleur d’arrière-plan à utiliser lors de l’aplatissement d’une image pour la transformer au format de sortie demandé.

Par défaut, Sharp utilise un fond noir lors de l’aplatissement d’une image. Spécifier une couleur de fond différente est particulièrement utile lors de la conversion d’images à fond transparent vers un format ne prenant pas en charge la transparence (par exemple, .jpeg).

src/components/MonComposant.astro

<Image
  src={monImage}
  alt="Une description de mon image"
  format="jpeg"
  background="#ffffff"
/>

Les valeurs sont transmises directement au service d’images. Sharp accepte toute valeur que le package color-string peut analyser.

<Picture />

Ajouté à la version : astro@3.3.0

Le composant <Picture /> génère une image optimisée avec plusieurs formats et/ou tailles.

src/pages/index.astro

---
import { Picture } from 'astro:assets';
import monImage from "../assets/mon_image.png"; // La résolution de l'image est de 1600x900
---

<!-- `alt` est obligatoire sur le composant Picture -->
<Picture src={monImage} formats={['avif', 'webp']} alt="Une description de mon image." />

<!-- Sortie -->
<picture>
  <source srcset="/_astro/mon_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/mon_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/mon_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>

<Picture /> accepte toutes les propriétés du composant <Image /> en plus des suivantes :

formats

Type : ImageOutputFormat[]

Un tableau de formats d’image à utiliser pour les balises <source>. Les entrées seront ajoutées en tant qu’éléments <source> dans l’ordre dans lequel elles sont répertoriées, et cet ordre détermine le format affiché. Pour de meilleures performances, indiquez d’abord le format le plus moderne (par exemple webp ou avif). Par défaut, ce paramètre est défini sur ['webp'].

fallbackFormat

Type : ImageOutputFormat

Format à utiliser comme valeur de secours pour la balise <img>. La valeur par défaut est .png pour les images statiques (ou .jpg si l’image est au format JPG), .gif pour les images animées et .svg pour les fichiers SVG.

pictureAttributes

Type : HTMLAttributes<'picture'>

Un objet d’attributs à ajouter à la balise <picture>.

Utilisez cette propriété pour appliquer des attributs à l’élément externe <picture> lui-même. Les attributs appliqués directement au composant <Picture /> s’appliqueront à l’élément interne <img>, à l’exception de ceux utilisés pour la transformation d’image.

src/components/MonComposant.astro

---
import { Picture } from "astro:assets";
import monImage from "../mon_image.png"; // La résolution de l'image est de 1600x900
---

<Picture
  src={monImage}
  alt="Une description de mon image."
  pictureAttributes={{ style: "background-color: red;" }}
/>

<!-- Sortie -->
<picture style="background-color: red;">
  <source srcset="/_astro/mon_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/mon_image.hash.png"
    alt="Une description de mon image."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>

<Font />

Ajouté à la version : astro@6.0.0 Nouveau

Le composant <Font /> génère des balises de style et peut éventuellement générer des liens de préchargement pour une famille de polices donnée.

Il doit être importé et ajouté dans l’élément <head> votre page. Cela se fait généralement dans un composant tel que Head.astro, utilisé dans la mise en page commune d’un site pour une utilisation globale, mais qui peut être ajouté à des pages individuelles selon les besoins.

Ce composant vous permet de contrôler quelle famille de polices est utilisée sur quelle page, et quelles polices sont préchargées.

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" preload />

Le composant <Font /> accepte les propriétés suivantes :

cssVariable (requise)

Type : CssVariable
Exemple de type : "--font-roboto" | "--font-comic-sans" | ...

La variable CSS (cssVariable) enregistrée dans votre configuration d’Astro :

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" />

preload

Type : boolean | { weight?: string | number; style?: string; subset?: string }[]
Par défaut : false

Détermine s’il faut afficher les liens de préchargement. Avec la directive preload, le navigateur commencera immédiatement à télécharger tous les liens de police disponibles lors du chargement de la page.

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font cssVariable="--font-roboto" preload />

Il n’est pas toujours souhaitable de précharger tous les liens de police, car cela peut bloquer le chargement d’autres ressources importantes ou télécharger des polices inutiles pour la page actuelle.

Pour contrôler sélectivement les fichiers de police à précharger, vous pouvez fournir un tableau d’objets décrivant toute combinaison de graisse (weight), style ou sous-ensemble (subset) de police à précharger :

src/components/Head.astro

---
import { Font } from "astro:assets";
---

<Font
  cssVariable="--font-roboto"
  preload={[
    { subset: "latin", style: "normal" },
    { weight: "400" },
  ]}
/>

Les fichiers de polices à graisse variable seront préchargés si une graisse comprise dans leur plage est demandée. Par exemple, un fichier de police pour la graisse 100 900 sera inclus si 400 est spécifié dans un objet preload.

getImage()

Type : (options: UnresolvedImageTransform) => Promise<GetImageResult>

Attention

La fonction getImage() repose sur des API réservées au serveur et générera une erreur côté client.

Si vous avez besoin de l’URL de l’image résultante côté client, vous pouvez transmettre au client la src obtenue par un appel à getImage() effectué sur le serveur.

La fonction getImage() est prévue pour générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une route d’API. Elle vous permet également de créer votre propre composant <Image /> personnalisé.

Cette fonction prend un objet d’options avec les mêmes propriétés que le composant Image (sauf alt) et renvoie un objet GetImageResult.

L’exemple suivant génère un arrière-plan (background-image) au format AVIF pour un élément <div /> :

src/components/ArrierePlan.astro

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}><slot /></div>

inferRemoteSize()

Type : (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Ajouté à la version : astro@4.12.0

Une fonction permettant de définir automatiquement la largeur et la hauteur d’origine d’une image distante. Elle peut être utilisée comme alternative à la transmission de la propriété inferSize.

import { inferRemoteSize } from 'astro:assets';
const { width, height } = await inferRemoteSize("https://example.com/cat.png");

getConfiguredImageService()

Type : () => Promise<ImageService>

Ajouté à la version : astro@2.1.3

Récupère le service d’image résolu.

imageConfig

Type : AstroConfig["image"]

Ajouté à la version : astro@3.0.9

Les options de configuration pour les images définies par l’utilisateur et fusionnées avec toutes les valeurs par défaut.

fontData

Type : Record<CssVariable, Array<FontData>>

Ajouté à la version : astro@6.0.0 Nouveau

Un objet où chaque clé est une variable CSS (cssVariable) et la valeur est un tableau décrivant les polices associées. Chaque police est un objet contenant un tableau de src disponibles pour cette police et les propriétés facultatives suivantes : weight et style :

import { fontData } from "astro:assets"

const data = fontData["--font-roboto"]

Types d’astro:assets

Les types suivants sont importés depuis le module virtuel des ressources :

import type {
  LocalImageProps,
  RemoteImageProps,
  FontData
} from "astro/assets";

LocalImageProps

Type : ImageSharedProps<T> & { src: ImageMetadata | Promise<{ default: ImageMetadata; }> }

Décrit les propriétés d’une image locale. Cela garantit que src correspond à la forme d’une image importée.

Apprenez-en davantage sur les images importées dans src/ avec un exemple d’utilisation.

RemoteImageProps

Types :

• ImageSharedProps<T> & { src: string; inferSize: true; }
• ImageSharedProps<T> & { src: string; inferSize?: false | undefined; }

Décrit les propriétés d’une image distante. Cela garantit que lorsque inferSize n’est pas fourni ou est défini sur false, les propriétés width et height sont toutes deux requises.

FontData

Type : { src: Array<{ url: string; format?: string; tech?: string }>; weight?: string; style?: string; }

Ajouté à la version : astro@6.0.0 Nouveau

Décrit les données de police associées à une famille de polices donnée.

Importations depuis astro/assets

Les utilitaires suivants sont importés du module standard des ressources :

import {
  baseService,
  getConfiguredImageService,
  getImage,
  isLocalService,
} from "astro/assets";

baseService

Type : Omit<LocalImageService, ‘transform’>

Le service d’images local intégré qui peut être étendu pour créer un service d’images personnalisé.

L’exemple suivant réutilise baseService pour créer un nouveau service d’images :

src/image-service.ts

import { baseService } from "astro/assets";

const newImageService = {
 getURL: baseService.getURL,
 parseURL: baseService.parseURL,
 getHTMLAttributes: baseService.getHTMLAttributes,
 async transform(inputBuffer, transformOptions) {...}
}

getConfiguredImageService()

Voir getConfiguredImageService() dans astro:assets.

getImage()

Type : (options: UnresolvedImageTransform, imageConfig: AstroConfig[‘image’]) => Promise<GetImageResult>

Une fonction similaire à getImage() de astro:assets avec deux arguments requis : un objet options avec les mêmes propriétés que le composant Image et un deuxième objet pour la configuration de l’image.

isLocalService()

Type : (service: ImageService | undefined) => boolean

Vérifie le type d’un service d’image et renvoie true lorsqu’il s’agit d’un service local.

Types d’astro/assets

Les types suivants sont importés du module standard des ressources :

import type {
  LocalImageProps,
  RemoteImageProps,
} from "astro/assets";

LocalImageProps

Voir LocalImageProps dans astro:assets.

RemoteImageProps

Voir RemoteImageProps dans astro:assets.

Importations depuis astro/assets/utils

Les fonctions d’assistance suivantes sont importées depuis le répertoire utils du module standard des ressources et peuvent être utilisées pour créer un service d’images :

import {
  isRemoteAllowed,
  matchHostname,
  matchPathname,
  matchPattern,
  matchPort,
  matchProtocol,
  isESMImportedImage,
  isRemoteImage,
  resolveSrc,
  imageMetadata,
  emitImageMetadata,
  emitClientAsset,
  getOrigQueryParams,
  inferRemoteSize,
  propsToFilename,
  hashTransform,
} from "astro/assets/utils";

isRemoteAllowed()

Type : (src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: RemotePattern[] }) => boolean

Ajouté à la version : astro@4.0.0

Détermine si une ressource distante donnée, identifiée par son URL source, est autorisée en fonction des domaines et des modèles distants spécifiés.

import { isRemoteAllowed } from 'astro/assets/utils';

const url = new URL('https://example.com/images/test.jpg');
const domains = ['example.com', 'anotherdomain.com'];
const remotePatterns = [
  {
    protocol: 'https',
    hostname: 'images.example.com',
    pathname: '/**', // Autoriser tout chemin sous ce nom d'hôte
  }
];

isRemoteAllowed(url.href, { domains, remotePatterns }); // Sortie : `true`

matchHostname()

Type : (url: URL, hostname?: string, allowWildcard = false) => boolean

Ajouté à la version : astro@4.0.0

Compare le nom d’hôte d’une URL donnée à un nom d’hôte spécifié, avec prise en charge optionnelle des caractères génériques.

import { matchHostname } from 'astro/assets/utils';

const url = new URL('https://sub.example.com/chemin/de/la/ressource');

matchHostname(url, 'example.com'); // Sortie : `false`
matchHostname(url, 'example.com', true); // Sortie : `true`

matchPathname()

Type : (url: URL, pathname?: string, allowWildcard = false) => boolean

Ajouté à la version : astro@4.0.0

Compare le chemin d’accès d’une URL donnée à un modèle spécifié, avec prise en charge optionnelle des caractères génériques.

import { matchPathname } from 'astro/assets/utils';

const testURL = new URL('https://example.com/images/photo.jpg');

matchPathname(testURL, '/images/photo.jpg'); // Sortie : `true`
matchPathname(testURL, '/images/'); // Sortie : `false`
matchPathname(testURL, '/images/*', true); // Sortie : `true`

matchPattern()

Type : (url: URL, remotePattern: RemotePattern) => boolean

Ajouté à la version : astro@4.0.0

Évalue si une URL donnée correspond au modèle distant spécifié en fonction du protocole, du nom d’hôte, du port et du chemin d’accès.

import { matchPattern } from 'astro/assets/utils';

const url = new URL('https://images.example.com/photos/test.jpg');
const remotePattern = {
  protocol: 'https',
  hostname: 'images.example.com',
  pathname: '/photos/**', // Autoriser tous les fichiers sous /photos/
};

matchPattern(url, remotePattern); // Sortie : `true`

matchPort()

Type : (url: URL, port?: string) => boolean
Par défaut : true

Ajouté à la version : astro@4.0.0

Vérifie si le port de l’URL donnée correspond au port spécifié. Si aucun port n’est fourni, renvoie true.

import { matchPort } from 'astro/assets/utils';

const urlWithPort = new URL('https://example.com:8080/resource');
const urlWithoutPort = new URL('https://example.com/resource');

matchPort(urlWithPort, '8080'); // Sortie : `true`
matchPort(urlWithoutPort, '8080'); // Sortie : `false`

matchProtocol()

Type : (url: URL, protocol?: string) => boolean
Par défaut : true

Ajouté à la version : astro@4.0.0

Compare le protocole de l’URL fournie avec un protocole spécifié. Renvoie true si le protocole correspond ou si aucun protocole n’est fourni.

import { matchProtocol } from 'astro/assets/utils';

const secureUrl = new URL('https://example.com/ressource');
const regularUrl = new URL('http://example.com/ressource');

matchProtocol(secureUrl, 'https'); // Sortie : `true`
matchProtocol(regularUrl, 'https'); // Sortie : `false`

isESMImportedImage()

Type : (src: ImageMetadata | string) => boolean

Ajouté à la version : astro@4.0.0

Détermine si la source donnée est une image importée en tant que module ECMAScript (ESM).

import { isESMImportedImage } from 'astro/assets/utils';

const imageMetadata = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const filePath = '/images/photo.jpg';

isESMImportedImage(imageMetadata); // Sortie : `true`
isESMImportedImage(filePath); // Sortie : `false`

isRemoteImage()

Type : (src: ImageMetadata | string) => boolean

Ajouté à la version : astro@4.0.0

Détermine si la source fournie est une URL d’image distante sous forme de chaîne de caractères.

import { isRemoteImage } from 'astro/assets/utils';

const imageUrl = 'https://example.com/images/photo.jpg';
const localImage = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};

isRemoteImage(imageUrl); // Sortie : `true`
isRemoteImage(localImage); // Sortie : `false`

resolveSrc()

Type : (src: UnresolvedImageTransform[‘src’]) => Promise<string | ImageMetadata>

Ajouté à la version : astro@4.0.0

Renvoie la source de l’image. Cette fonction garantit que si src est une promesse (par exemple, une importation dynamique (import())), elle est attendue et que la valeur correcte de src est extraite. Si src est déjà une valeur résolue, elle est renvoyée telle quelle.

import { resolveSrc } from 'astro/assets/utils';
import localImage from "./images/photo.jpg";

const resolvedLocal = await resolveSrc(localImage);
// Exemple de valeur : `{ src: '/@fs/home/nom-utilisateur/dev/projet-astro/src/images/photo.jpg', width: 800, height: 600, format: 'jpg' }`

const resolvedRemote = await resolveSrc("https://example.com/img-distante.jpg");
// Value: `"https://example.com/img-distante.jpg"`

const resolvedDynamic = await resolveSrc(import("./images/image-dynamique.jpg"))
// Exemple de valeur : `{ src: '/@fs/home/nom-utilisateur/dev/projet-astro/src/images/image-dynamique.jpg', width: 800, height: 600, format: 'jpg' }`

imageMetadata()

Type : (data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Ajouté à la version : astro@4.0.0

Extrait les métadonnées de l’image, telles que ses dimensions, son format et son orientation, à partir des données d’image fournies.

import { imageMetadata } from 'astro/assets/utils';

const binaryImage = new Uint8Array([/* ...données d'image binaires... */]);
const sourcePath = '/images/photo.jpg';

const metadata = await imageMetadata(binaryImage, sourcePath);
// Exemple de valeur :
// {
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    orientation: undefined
// }

emitImageMetadata()

Type : (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>

Ajouté à la version : astro@5.7.0

Traite un fichier image et émet ses métadonnées et éventuellement son contenu. En mode compilation, la fonction utilise fileEmitter pour générer une référence de ressource. En mode développement, cela se résout en une URL de fichier local avec des paramètres de requête pour les métadonnées.

import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const metadata = await emitImageMetadata(imageId);
// Exemple de valeur :
// {
//    src: '/@fs/home/nom-utilisateur/dev/projet-astro/src/images/photo.jpg?origWidth=800&origHeight=600&origFormat=jpg',
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    contents: Uint8Array([...])
// }

emitClientAsset()

Type : (pluginContext: Rollup.PluginContext, options: Rollup.EmitFile) => string

Ajouté à la version : astro@6.0.0 Nouveau

Génère une ressource client qui sera déplacée vers le répertoire client des ressources (p. ex. dist/client/_astro/) lors des compilations SSR. Cette fonction est destinée aux développeurs d’intégrations qui doivent générer des ressources (telles que des images) à partir de contenu rendu côté serveur et accessibles côté client.

Utilisez ceci directement au lieu de Rollup pluginContext.emitFile() lorsque vous travaillez dans un contexte de module d’extension pour Vite et que vous avez besoin que la ressource émise soit déplacée vers le répertoire de sortie du client.

import { emitClientAsset } from 'astro/assets/utils';

function myVitePlugin() {
  return {
    name: 'my-plugin',
    transform(code, id) {
      const handle = emitClientAsset(this, {
        type: 'asset',
        name: 'my-image.png',
        source: imageBuffer,
      });
      // Renvoie l'identifiant de la ressource similaire à `emitFile()`
    }
  }
}

getOrigQueryParams()

Type : (params: URLSearchParams) => Pick<ImageMetadata, ‘width’ | ‘height’ | ‘format’> | undefined

Ajouté à la version : astro@4.0.0

Récupère la largeur (width), la hauteur (height) et le format d’une image à partir d’un objet URLSearchParams. Si l’un de ces paramètres est manquant ou invalide, la fonction renvoie undefined.

import { getOrigQueryParams } from 'astro/assets/utils';

const url = new URL('https://example.com/image.jpg?width=800&height=600&format=jpg');
const origParams = getOrigQueryParams(url.searchParams);
// Exemple de valeur :
// {
//    width: 800,
//    height: 600,
//    format: 'jpg'
// }

inferRemoteSize()

Type : (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Ajouté à la version : astro@4.0.0

Déduit les dimensions d’une image distante en diffusant ses données et en les analysant progressivement jusqu’à ce que suffisamment de métadonnées soient disponibles.

import { inferRemoteSize } from 'astro/assets/utils';

const remoteImageUrl = 'https://example.com/image.jpg';
const imageSize = await inferRemoteSize(remoteImageUrl);
// Exemple de valeur :
// {
//    width: 1920,
//    height: 1080,
//    format: 'jpg'
// }

propsToFilename()

Type : (filePath: string, transform: ImageTransform, hash: string) => string

Ajouté à la version : astro@4.0.0

Génère un nom de fichier formaté pour une image en fonction de son chemin source, de ses propriétés de transformation et d’un hachage unique.

Le nom de fichier formaté suit cette structure :

<prefixDirname>/<baseFilename>_<hash><outputExtension>

• prefixDirname : Si l’image est une image importée ESM, il s’agit du nom du répertoire du chemin du fichier d’origine ; sinon, ce sera une chaîne de caractères vide.
• baseFilename : Le nom de base du fichier ou un nom court haché si le fichier est un URI data:.
• hash : Une chaîne de hachage unique générée pour distinguer le fichier transformé.
• outputExtension : L’extension du fichier de sortie souhaitée dérivée de transform.format ou de l’extension du fichier d’origine.

import { propsToFilename } from 'astro/assets/utils';

const filePath = '/images/photo.jpg';
const transform = { format: 'png', src: filePath };
const hash = 'abcd1234';

const filename = propsToFilename(filePath, transform, hash);
// Exemple de valeur : '/images/photo_abcd1234.png'

hashTransform()

Type : (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string

Ajouté à la version : astro@4.0.0

Transforme l’objet transform fourni en une chaîne de hachage basée sur les propriétés sélectionnées et le service d’images (imageService) spécifié.

import { hashTransform } from 'astro/assets/utils';

const transform = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const imageService = 'astro/assets/services/sharp';
const propertiesToHash = ['width', 'height', 'format'];

const hash = hashTransform(transform, imageService, propertiesToHash);
// Exemple de valeur : 'd41d8cd98f00b204e9800998ecf8427e'

Types d’astro

import type {
  GetImageResult,
  ImageTransform,
  UnresolvedImageTransform,
  ImageMetadata,
  ImageInputFormat,
  ImageOutputFormat,
  ImageQuality,
  ImageQualityPreset,
  RemotePattern,
  ImageService,
  ExternalImageService,
  LocalImageService,
  ImageServiceConfig,
} from "astro";

GetImageResult

Type : object

Ajouté à la version : astro@2.2.0

Décrit le résultat de la transformation après l’appel à getImage().

GetImageResult.attributes

Type : Record<string, any>

Définit les attributs HTML supplémentaires nécessaires au rendu de l’image (par exemple, largeur, hauteur, style).

GetImageResult.options

Type : ImageTransform

Décrit les paramètres de transformation après validation.

GetImageResult.rawOptions

Type : ImageTransform

Décrit les paramètres de transformation d’origine.

GetImageResult.src

Type : string

Le chemin d’accès à l’image générée.

GetImageResult.srcSet

Type : { values: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }

Ajouté à la version : astro@3.3.0

Un objet décrivant comment générer l’attribut srcset.

GetImageResult.srcSet.values

Type : { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]

Un tableau de valeurs générées où chaque entrée comprend une URL et un descripteur de taille. Celui-ci peut être utilisé pour générer manuellement la valeur de l’attribut srcset.

GetImageResult.srcSet.attribute

Type : string

Une valeur prête à être utilisée dans l’attribut srcset.

ImageTransform

Type : object

Définit les options acceptées par le service de transformation d’images. Ceci contient une propriété src obligatoire, des propriétés prédéfinies facultatives et toutes les propriétés supplémentaires requises par le service d’images :

ImageTransform.src

Type : ImageMetadata | string

Définit le chemin d’accès à une image locale dans le répertoire public, l’URL d’une image distante ou les données d’une image importée.

ImageTransform.width

Type : number | undefined

La largeur de l’image.

ImageTransform.height

Type : number | undefined

La hauteur de l’image.

ImageTransform.widths

Type : number[] | undefined

Ajouté à la version : astro@3.3.0

Une liste de largeurs à générer pour l’image.

ImageTransform.densities

Type : (number | `${number}x`)[] | undefined

Ajouté à la version : astro@3.3.0

Une liste de densités de pixels à générer pour l’image.

ImageTransform.quality

Type : ImageQuality | undefined

La qualité souhaitée pour l’image de sortie.

ImageTransform.format

Type : ImageOutputFormat | undefined

Le format souhaité pour l’image de sortie.

ImageTransform.fit

Type : 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | string | undefined

Ajouté à la version : astro@5.0.0

Définit une liste de valeurs autorisées pour la propriété CSS object-fit, extensible avec n’importe quelle chaîne de caractères.

ImageTransform.position

Type : string | undefined

Ajouté à la version : astro@5.0.0

Contrôle la valeur de la propriété CSS object-position.

UnresolvedImageTransform

Type : Omit<ImageTransform, “src”> & { src: ImageMetadata | string | Promise<{ default: ImageMetadata }>; inferSize?: boolean; }

Représente une image avec des options de transformation. Ceci contient les mêmes propriétés que le type ImageTransform avec un type src différent et une propriété inferSize supplémentaire.

UnresolvedImageTransform.src

Type : ImageMetadata | string | Promise<{ default: ImageMetadata }>

Le chemin d’accès à une image importée ou située dans le répertoire public, ou l’URL d’une image distante.

UnresolvedImageTransform.inferSize

Type : boolean

Détermine si la largeur et la hauteur de l’image doivent être déduites.

Voir aussi l’attribut inferSize disponible pour <Image />.

ImageMetadata

Type : { src: string; width: number; height: number; format: ImageInputFormat; orientation?: number; }

Ajouté à la version : astro@2.1.3

Décrit les données collectées lors de l’importation d’images. Ceci contient les propriétés suivantes :

ImageMetadata.src

Type : string

Le chemin absolu de l’image sur le système de fichiers.

ImageMetadata.width

Type : number

La largeur de l’image.

ImageMetadata.height

Type : number

La hauteur de l’image.

ImageMetadata.format

Type : ImageInputFormat

Le format de l’image.

ImageMetadata.orientation

Type : number

Ajouté à la version : astro@2.8.3

L’orientation de l’image lorsque ses métadonnées contiennent cette information.

ImageInputFormat

Type : "jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"

Ajouté à la version : astro@2.2.0

Décrit une union des formats pris en charge pour les images importées.

ImageOutputFormat

Type : string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"

Ajouté à la version : astro@2.2.0

Spécifie le format des images de sortie. Il peut s’agir d’une valeur littérale prédéfinie ou de n’importe quelle chaîne de caractères.

ImageQuality

Type : ImageQualityPreset | number

Ajouté à la version : astro@2.2.0

Représente la qualité perceptive de l’image de sortie sous forme d’une union de valeurs littérales prédéfinies, d’une chaîne de caractères ou d’un nombre.

ImageQualityPreset

Type : string | "low" | "mid" | "high" | "max"

Ajouté à la version : astro@2.2.0

Définit les préréglages disponibles pour contrôler la qualité d’image, extensibles avec n’importe quelle chaîne de caractères.

RemotePattern

Type : { hostname?: string; pathname?: string; protocol?: string; port?: string; }

Ajouté à la version : astro@5.14.2

Décrit un hôte distant à travers quatre propriétés facultatives : hostname, pathname, protocol et port.

ImageService

Type : ExternalImageService | LocalImageService

Définit les hooks qu’un service d’images local ou externe doit fournir.

ExternalImageService

Type : object

Définit les hooks qu’un service de transformation d’images externe doit fournir. Cela nécessite un hook getUrl() et prend en charge trois hooks supplémentaires.

Apprenez à créer des services externes dans la référence de l’API des services d’images avec des exemples d’utilisation.

LocalImageService

Type : object

Définit les hooks qu’un service local de transformation d’images doit fournir. Cela nécessite les hooks getUrl(), parseUrl() et transform(), et prend en charge des hooks supplémentaires.

Apprenez à créer des services locaux dans la référence de l’API des services d’images avec des exemples d’utilisation.

ImageServiceConfig

Type : { entrypoint: 'astro/assets/services/sharp' | string; config?: T; }

Ajouté à la version : astro@2.3.3

Décrit l’objet de configuration d’un service d’images. Celui-ci contient les propriétés suivantes :

ImageServiceConfig.entrypoint

Type : 'astro/assets/services/sharp' | string

Un paquet ou un chemin d’accès au module de service d’images. Il peut s’agir du service Sharp intégré à Astro ou d’un service tiers.

ImageServiceConfig.config

Type : Record<string, any>

Un objet de configuration transmis au service d’images. Sa structure dépend du service utilisé.