Images

Astro vous propose plusieurs façons d’utiliser des images sur votre site, qu’elles soient stockées localement dans votre projet, liées à une URL externe ou gérées dans un CMS ou un CDN.

Astro fournit des composants Image et Picture, le traitement de la syntaxe d’image Markdown, des composants SVG et une fonction de génération d’images pour optimiser et/ou transformer vos images. De plus, vous pouvez configurer le redimensionnement automatique des images adaptatives par défaut, ou définir des propriétés adaptatives sur des composants Image et Picture individuels.

Vous pouvez toujours choisir d’utiliser des images et des fichiers SVG en utilisant des éléments HTML natifs dans les fichiers .astro ou Markdown, ou la manière standard pour votre type de fichier (par exemple <img /> dans MDX et JSX). Cependant, Astro n’effectue aucun traitement ni optimisation de ces images.

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Où stocker les images

src/ vs public/

Nous recommandons que les images locales soient conservées dans src/ si possible afin qu’Astro puisse les transformer, les optimiser et les regrouper. Les fichiers dans le répertoire public/ sont toujours servis ou copiés dans le dossier de compilation tels quels, sans aucun traitement.

Vos images locales stockées dans src/ peuvent être utilisées par tous les fichiers de votre projet : .astro, .md, .mdx, .mdoc et d’autres frameworks d’interface utilisateur sous forme d’importations de fichiers. Les images peuvent être stockées dans n’importe quel dossier, y compris avec votre contenu.

Stockez vos images dans le dossier public/ pour éviter tout traitement. Ces images sont disponibles dans vos fichiers de projet sous forme d’URL sur votre domaine et vous permettent d’avoir un lien public direct vers elles. Par exemple, le favicon de votre site sera généralement placé à la racine de ce dossier où les navigateurs pourront l’identifier.

Images distantes

Vous pouvez également choisir de stocker vos images à distance, dans un système de gestion de contenu (CMS) ou une plateforme de gestion des ressources numériques (DAM). Astro peut récupérer vos données à distance à l’aide d’API ou afficher des images à partir de leur chemin d’accès complet.

Pour une protection supplémentaire lors du traitement de sources externes, les composants d’image et la fonction d’assistance d’Astro traiteront uniquement (par exemple, optimiseront, transformeront) les images provenant de sources d’images autorisées spécifiées dans votre configuration. Les images distantes provenant d’autres sources seront affichées sans traitement.

Images dans les fichiers .astro

Options : <Image />, <Picture />, <img>, <svg>, composants SVG

Le langage de création de modèles d’Astro vous permet de générer des images optimisées avec le composant <Image /> d’Astro et de générer plusieurs tailles et formats avec le composant <Picture /> d’Astro. Ces deux composants acceptent également les propriétés d’image adaptatives pour un redimensionnement en fonction de la taille du conteneur et de la taille et de la résolution de l’écran de l’appareil.

De plus, vous pouvez importer et utiliser des fichiers SVG comme composants Astro dans les composants .astro.

Toutes les balises HTML natives, y compris <img> et <svg>, sont également disponibles dans les composants .astro. Les images affichées avec des balises HTML ne seront pas traitées (par exemple optimisées, transformées) et seront copiées telles quelles dans votre dossier de compilation.

Pour toutes les images dans les fichiers .astro, la valeur de l’attribut src de l’image est déterminée par l’emplacement de votre fichier image :

• Une image locale dans le dossier src/ de votre projet utilise une importation à partir du chemin relatif du fichier.

  Les composants Image et Picture utilisent directement l’importation nommée (par exemple src={rocket}), tandis que la balise <img> utilise la propriété d’objet src de l’importation (par exemple src={rocket.src}).

• Les images distantes et celles présentes dans public/ utilisent une URL.

  Fournissez une URL complète pour les images distantes (par exemple, src="https://www.example.com/images/mon-image-distante.jpg"), ou une URL relative à votre site qui correspond à l’emplacement de votre fichier dans votre dossier public/ (par exemple, src="/images/mon-image-publique.jpg" pour une image située dans public/images/mon-image-publique.jpg).

src/pages/blog/my-images.astro

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un oiseau assis sur un nid d'œufs." />
<Image src="/images/bird-in-public-folder.jpg" alt="Un oiseau." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Un oiseau." width="50" height="50" />

<img src={localBirdImage.src} alt="Un oiseau assis sur un nid d'œufs.">
<img src="/images/bird-in-public-folder.jpg" alt="Un oiseau.">
<img src="https://example.com/remote-bird.jpg" alt="Un oiseau.">

Consultez la référence complète de l’API des composants <Image /> et <Picture />, y compris les propriétés obligatoires et facultatives.

Méthode associée : Importer dynamiquement des images

Images dans les fichiers Markdown

Options : ![](), <img> (avec des images publiques ou distantes)

Utilisez la syntaxe Markdown standard ![alt](src) dans vos fichiers .md. Vos images locales stockées dans src/ et les images distantes seront traitées et optimisées. Lorsque vous configurez des images adaptatives globalement, ces images seront également adaptatives.

Les images placées dans le dossier public/ ne sont jamais optimisées.

src/pages/post-1.md

# Ma page Markdown

<!-- Image locale placée dans src/assets/ -->
<!-- Utiliser un chemin de fichier relatif ou un alias d'importation -->
![Un ciel étoilé.](../assets/stars.png)

<!-- Image placée dans public/images/ -->
<!-- Utiliser le chemin du fichier relatif à public/ -->
![Un ciel étoilé.](/images/stars.png)

<!-- Image distante sur un autre serveur -->
<!-- Utiliser l'URL complète de l'image -->
![Astro](https://example.com/images/image-distante.png)

La balise HTML <img> peut également être utilisée pour afficher des images placées dans public/ ou des images distantes sans aucune optimisation ou traitement d’image. Cependant, <img> n’est pas prise en charge pour vos images locales dans src.

Les composants <Image /> et <Picture /> ne sont pas disponibles dans les fichiers .md. Si vous avez besoin de plus de contrôle sur les attributs de votre image, nous vous recommandons d’utiliser l’intégration MDX d’Astro pour ajouter la prise en charge du format de fichier .mdx. MDX offre des options d’image supplémentaires disponibles dans MDX, notamment la combinaison de composants avec la syntaxe Markdown.

Images dans les fichiers MDX

Options : <Image />, <Picture />, <img />, ![](), composants SVG

Vous pouvez utiliser les composants <Image /> et <Picture /> d’Astro dans vos fichiers .mdx en important à la fois le composant et votre image. Utilisez-les tels qu’ils sont utilisés dans les fichiers .astro. La balise JSX <img /> est également prise en charge pour les images non traitées et utilise la même importation d’image que la balise HTML <img>.

De plus, il existe une prise en charge de la syntaxe Markdown standard ![alt](src) sans importation requise.

src/pages/post-1.mdx

---
title: Le titre de ma page
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Ma page MDX

// Image locale placée dans le même dossier
![Houston dans la nature](houston.png)

// Image locale placée dans src/assets/
<Image src={rocket} alt="Une fusée dans l'espace." />
<img src={rocket.src} alt="Une fusée dans l'espace." />
![Une fusée dans l'espace](../assets/rocket.png)

// Image placée dans public/images/
<Image src="/images/stars.png" alt="Un ciel étoilé." />
<img src="/images/stars.png" alt="Un ciel étoilé." />
![Un ciel étoilé.](/images/stars.png)

// Image distante sur un autre serveur
<Image src="https://example.com/images/image-distante.png" />
<img src="https://example.com/images/image-distante.png" />
![Astro](https://example.com/images/image-distante.png)

Consultez la référence complète de l’API pour les composants <Image /> et <Picture />.

Images dans les composants de framework UI

Options d’image : la syntaxe d’image propre au framework (par exemple <img /> dans JSX, <img> dans Svelte)

Les images locales doivent d’abord être importées pour accéder à leurs propriétés d’image telles que src. Ensuite, elles peuvent être rendues comme vous le feriez normalement dans la syntaxe d’image propre à ce framework :

src/components/ReactImage.jsx

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="Un ciel étoilé." />
  )
}

src/components/SvelteImage.svelte

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="Un ciel étoilé." />

Les composants Astro (par exemple <Image />, <Picture />, composants SVG) ne sont pas disponibles dans les composants de framework UI car un îlot de client doit contenir uniquement du code valide pour son propre framework.

Mais vous pouvez transmettre le contenu statique généré par ces composants à un composant de framework dans un fichier .astro en tant qu’enfants ou en utilisant un <slot/> nommé :

src/components/ImageWrapper.astro

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="Un ciel étoilé." />
</ReactComponent>

Composants Astro pour les images

Astro fournit deux composants Astro intégrés pour les images (<Image /> et <Picture />) et vous permet également d’importer des fichiers SVG et de les utiliser comme composants Astro. Ces composants peuvent être utilisés dans tous les fichiers pouvant importer et restituer des composants .astro.

<Image />

Utilisez le composant Astro intégré <Image /> pour afficher des versions optimisées :

• de vos images locales situées dans le dossier src/
• d’images distantes configurées provenant de sources autorisées

<Image /> peut transformer les dimensions, le type de fichier et la qualité d’une image locale ou distante autorisée pour contrôler l’image affichée. Cette transformation s’effectue lors de la création des pages pré-rendues. Si votre page est rendue à la demande, elle s’effectue à la volée lors de son affichage. La balise <img> résultante inclut les attributs alt, loading et decoding et déduit les dimensions de l’image pour éviter le décalage cumulatif de mise en page (« Cumulative Layout Shift » en anglais ou CLS).

Qu’est-ce que le décalage cumulatif de la mise en page ?

Cumulative Layout Shift (CLS) est une mesure de Core Web Vital qui permet d’évaluer le décalage du contenu de votre page pendant le chargement. Le composant <Image /> optimise le CLS en définissant automatiquement la bonne largeur (width) et la bonne hauteur (height) pour vos images locales.

src/components/MyComponent.astro

---
// importer le composant Image et l'image
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est en 1600x900
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="La description de mon image." />

<!-- Résultat du pré-rendu -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="La description de mon image."
/>

<!-- Résultat du rendu à la demande -->
<!-- src utilisera un point de terminaison généré à la demande -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

Le composant <Image /> accepte plusieurs propriétés de composant ainsi que tous les attributs acceptés par la balise HTML <img>.

L’exemple suivant fournit une classe (class) au composant Image qui s’appliquera à l’élément final <img>.

src/pages/index.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` est obligatoire pour le composant Image -->
<Image src={myImage} alt="" class="my-class" />

<!-- Résultat du pré-rendu -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

Astuce

Vous pouvez également utiliser le composant <Image /> pour les images du dossier public/ ou les images distantes non spécifiquement configurées dans votre projet, même si ces images ne seront ni optimisées ni traitées. L’image résultante sera la même que celle obtenue en utilisant la balise HTML <img>.

Cependant, l’utilisation du composant Image pour toutes les images offre une expérience de création cohérente et empêche le décalage de mise en page cumulé (CLS), même pour vos images non optimisées.

<Picture />

Ajouté à la version : astro@3.3.0

Utilisez le composant Astro intégré <Picture /> pour générer une balise <picture> avec plusieurs formats et/ou tailles d’images. Cela vous permet de spécifier les formats de fichiers préférés à afficher et en même temps, de fournir un format de repli. Comme le composant <Image />, les images seront traitées au moment de la compilation pour les pages pré-rendues. Lorsque votre page est rendue à la demande, le traitement se produira à la volée lorsque la page sera consultée.

L’exemple suivant utilise le composant <Picture /> pour transformer un fichier .png local en un format avif et webp convivial pour le web ainsi que l’image au format .png avec la balise <img> qui peut être affichée comme solution de repli si nécessaire :

src/pages/index.astro

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image est de 1600x900
---

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

<!-- Résultat du pré-rendu -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>

Consultez le détail des propriétés du composant <Picture /> dans la référence astro:assets.

Comportement des images adaptatives

Ajouté à la version : astro@5.10.0 Nouveau

Les images adaptatives sont des images qui s’ajustent pour améliorer les performances sur différents appareils. Ces images peuvent être redimensionnées pour s’adapter à leur conteneur et peuvent être diffusées dans différentes tailles en fonction de la taille et de la résolution de l’écran de votre visiteur.

Avec les propriétés d’image adaptatives appliquées aux composants <Image /> ou <Picture />, Astro générera automatiquement les valeurs srcset et sizes requises pour vos images, et appliquera les styles nécessaires pour garantir qu’elles se redimensionnent correctement.

Lorsque ce comportement adaptatif est configuré globalement, il s’appliquera à tous les composants d’image ainsi qu’à toutes les images locales et distantes utilisant la syntaxe Markdown ![]().

Les images de votre dossier public/ ne sont jamais optimisées et les images adaptatives ne sont pas prises en charge.

Note

Une seule image adaptative générera plusieurs images de différentes tailles afin que le navigateur puisse afficher la meilleure à votre visiteur.

Pour les pages pré-rendues, cela se produit pendant la compilation et peut augmenter le temps de compilation de votre projet, surtout si vous avez un grand nombre d’images.

Pour les pages rendues à la demande, les images sont générées au fur et à mesure des visites. Cela n’a aucun impact sur les délais de création, mais peut augmenter le nombre de transformations d’image effectuées lors de l’affichage. Selon votre service d’images, cela peut entraîner des frais supplémentaires.

En savoir plus sur les images adaptatives dans la documentation de MDN.

Sortie HTML générée pour les images adaptatives

Lorsqu’une mise en page est définie, soit par défaut, soit sur un composant individuel, les attributs srcset et sizes des images sont automatiquement générés en fonction de leurs dimensions et de leur type de mise en page. Les images avec des mises en page constrained et full-width se verront appliquer des styles pour garantir leur redimensionnement en fonction de leur conteneur.

src/components/MyComponent.astro

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

Ce composant <Image /> générera la sortie HTML suivante sur une page pré-rendue :

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_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"
>

Styles des images adaptatives

Définir image.responsiveStyles: true applique un petit nombre de styles globaux pour garantir le bon redimensionnement de vos images. Dans la plupart des cas, il est préférable de les activer par défaut ; vos images ne seront pas adaptatives sans styles supplémentaires.

Cependant, si vous préférez gérer vous-même le style des images adaptatives ou si vous devez remplacer ces valeurs par défaut lors de l’utilisation de Tailwind 4, laissez la valeur false configurée par défaut.

Les styles globaux appliqués par Astro dépendent du type de mise en page et sont conçus pour produire le meilleur résultat pour les attributs srcset et sizes générés. Voici les styles par défaut :

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%;
}

Les styles utilisent la pseudo-classe :where(), qui a une spécificité de 0, ce qui signifie qu’il est facile de la remplacer par vos propres styles. Tout sélecteur CSS aura une spécificité supérieure à :where() ; vous pouvez donc facilement remplacer les styles en ajoutant vos propres styles pour cibler l’image.

Vous pouvez remplacer les styles object-fit et object-position image par image en définissant les props fit et position sur le composant <Image /> ou <Picture />.

Images adaptatives avec Tailwind 4

Tailwind 4 est compatible avec les styles adaptatifs par défaut d’Astro. Cependant, Tailwind utilise des couches en cascade, ce qui signifie que ses règles ont toujours une spécificité inférieure à celle des règles qui n’utilisent pas de couches, y compris les styles adaptatifs d’Astro. Par conséquent, les styles d’Astro auront la priorité sur les styles de Tailwind. Pour utiliser les règles Tailwind au lieu des styles par défaut d’Astro, n’activez pas les styles adaptatifs par défaut d’Astro.

Composants SVG

Ajouté à la version : astro@5.7.0

Astro vous permet d’importer des fichiers SVG et de les utiliser comme composants Astro. Astro intègre le contenu SVG dans votre sortie HTML.

Référencez l’importation par défaut de tout fichier .svg local. Cette importation étant traitée comme un composant Astro, vous devez utiliser les mêmes conventions (par exemple, la casse) que pour l’utilisation de balises dynamiques.

src/components/MonComposantAstro.astro

---
import Logo from './chemin/vers/un/fichier.svg';
---

<Logo />

Votre composant SVG, comme <Image /> ou tout autre composant Astro, n’est pas disponible dans les composants de framework UI, mais peut être transmis à un composant du framework dans un composant .astro.

Attributs des composants SVG

Vous pouvez transmettre des props tels que width, height, fill, stroke et tout autre attribut accepté par l’élément natif <svg>. Ces attributs seront automatiquement appliqués à l’élément <svg> sous-jacent. Si une propriété est présente dans le fichier .svg d’origine et transmise au composant, la valeur transmise au composant remplacera la valeur d’origine.

src/components/MonComposantAstro.astro

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

Création de composants d’image personnalisés

Vous pouvez créer un composant d’image personnalisé et réutilisable en enveloppant le composant <Image /> ou <Picture/> dans un autre composant Astro. Cela vous permet de définir les attributs et les styles par défaut une seule fois.

Par exemple, vous pouvez créer un composant pour les images de vos articles de blog qui reçoit des attributs comme props et applique des styles cohérents à chaque image :

src/components/BlogPostImage.astro

---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

Afficher des images non traitées avec la balise HTML <img>

La syntaxe de modèle Astro prend également en charge l’écriture directe d’une balise <img>, avec un contrôle total sur sa sortie finale. Ces images ne seront ni traitées ni optimisées. Elle accepte toutes les propriétés de la balise HTML <img>, la seule propriété obligatoire étant src. Cependant, il est fortement recommandé d’inclure la propriété alt pour l’accessibilité.

Images dans src/

Les images locales doivent être importées à partir du chemin relatif du fichier .astro existant, ou vous pouvez configurer et utiliser un alias d’importation. Vous pouvez ensuite accéder à la source de l’image et aux autres propriétés à utiliser dans la balise <img>.

Les ressources d’image importées correspondent à la signature suivante :

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

L’exemple suivant utilise les propriétés « height » et « width » de l’image pour éviter le décalage de mise en page cumulé (CLS) et améliorer les Core Web Vitals :

src/pages/posts/post-1.astro

---
// importer des images locales
import myDog from '../../images/pets/local-dog.jpg';
---
// accéder aux propriétés de l'image
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un chien qui aboie." />

Images dans public/

Pour les images situées dans « public/ », utilisez le chemin d’accès au fichier de l’image par rapport au dossier public comme valeur pour src :

<img src="/images/public-cat.jpg" alt="Un chat endormi." >

Images distantes

Pour les images distantes, utilisez l’URL complète de l’image comme valeur pour src :

<img src="https://example.com/remote-cat.jpg" alt="Un chat endormi." >

Choisir entre <Image /> et <img>

Le composant <Image /> optimise votre image et déduit la largeur et la hauteur (pour les images qu’il peut traiter) en fonction du rapport hauteur/largeur d’origine pour éviter le CLS. C’est la méthode privilégiée pour utiliser les images dans les fichiers .astro chaque fois que cela est possible.

Utilisez l’élément HTML <img> lorsque vous ne pouvez pas utiliser le composant <Image />, par exemple :

• pour les formats d’image non pris en charge
• lorsque vous ne souhaitez pas que votre image soit optimisée par Astro
• pour accéder à et modifier l’attribut src de manière dynamique côté client

Utilisation d’images provenant d’un CMS ou d’un CDN

Les CDN d’images fonctionnent avec toutes les options d’images d’Astro. Utilisez l’URL complète d’une image comme attribut src dans le composant <Image />, une balise <img>, ou dans la notation Markdown. Pour l’optimisation des images distantes, il faut également configurer les domaines autorisés ou les modèles d’URL.

Alternativement, le CDN peut fournir ses propres SDK pour s’intégrer plus facilement dans un projet Astro. Par exemple, Cloudinary prend en charge un SDK Astro qui vous permet d’insérer facilement des images avec leur composant CldImage ou un SDK Node.js qui peut générer des URL à utiliser avec une balise <img> dans un environnement Node.js.

Consultez la référence complète de l’API des composants <Image /> et <Picture />.

Autoriser les images distantes

Vous pouvez configurer des listes de domaines et de modèles d’URL autorisés en tant que source d’image pour l’optimisation des images à l’aide de image.domains et image.remotePatterns. Cette configuration est une couche de sécurité supplémentaire pour protéger votre site lors de l’affichage d’images provenant d’une source externe.

Les images distantes provenant d’autres sources ne seront pas optimisées, mais l’utilisation du composant <Image /> pour ces images empêchera le décalage de mise en page cumulatif (CLS).

Par exemple, la configuration suivante permettra uniquement l’optimisation des images distantes provenant de astro.build :

astro.config.mjs

export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

La configuration suivante autorisera uniquement les images distantes provenant d’hôtes HTTPS :

astro.config.mjs

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Images dans les collections de contenu

Vous pouvez déclarer une image associée à une entrée de collection de contenu, telle que l’image de couverture d’un article de blog, dans votre frontmatter en utilisant son chemin relatif au dossier actuel :

src/content/blog/my-post.md

---
title: "Mon premier article de blog"
cover: "./firstpostcover.jpeg" # se résoudra en "src/content/blog/firstblogcover.jpeg"
coverAlt: "Photographie d'un coucher de soleil derrière une chaîne de montagnes."
---

Ceci est un article de blog

L’assistant image pour le schéma des collections de contenu vous permet de valider et d’importer l’image.

src/content.config.ts

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

L’image sera importée et transformée en métadonnées, vous permettant de la transmettre comme src à <Image/>, <img>, ou getImage() dans un composant Astro.

L’exemple ci-dessous montre une page d’index de blog qui affiche la photo de couverture et le titre de chaque article de blog en utilisant le schéma précédent :

src/pages/blog.astro

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
  allBlogPosts.map((post) => (
    <div>
      <Image src={post.data.cover} alt={post.data.coverAlt} />
      <h2>
        <a href={"/blog/" + post.slug}>{post.data.title}</a>
      </h2>
    </div>
  ))
}

Générer des images avec getImage()

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. Lorsque vous avez besoin d’options que les composants <Picture> et <Image> ne prennent pas actuellement en charge, vous pouvez utiliser la fonction getImage() pour créer votre propre composant <Image /> personnalisé.

Pour en savoir plus, consultez la référence getImage().

Méthode associée : Créer un composant image personnalisé

Texte alternatif

Tous les utilisateurs ne voient pas les images de la même manière. L’accessibilité est donc une préoccupation particulièrement importante lors de l’utilisation d’images. Utilisez l’attribut alt pour fournir un texte alternatif descriptif pour les images.

Cet attribut est requis pour les composants <Image /> et <Picture />. Si aucun texte alt n’est fourni, un message d’erreur utile vous rappellera d’inclure l’attribut alt.

Si l’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 sachent qu’ils doivent ignorer l’image.

Service d’images par défaut

Sharp est le service d’images par défaut utilisé pour astro:assets. Vous pouvez configurer le service d’images en utilisant l’option image.service.

Note

Lorsque vous utilisez un gestionnaire de paquets strict comme pnpm, vous pouvez avoir besoin d’installer manuellement Sharp dans votre projet même si c’est une dépendance d’Astro :

pnpm add sharp

Configurer le service no-op passthrough

Si votre adaptateur ne prend pas en charge l’optimisation d’image Sharp intégrée à Astro (par exemple Deno, Cloudflare), vous pouvez configurer un service d’image sans opération (ou « no-op » en anglais) pour vous permettre d’utiliser les composants <Image /> et <Picture />. Notez qu’Astro n’effectue aucune transformation ou traitement d’image dans ces environnements. Cependant, vous pouvez toujours profiter des autres avantages de l’utilisation de astro:assets, y compris l’absence de décalage cumulatif de la mise en page (CLS), l’application de l’attribut alt, et une expérience de création cohérente.

Configurez passthroughImageService() pour éviter les traitements d’image Sharp :

astro.config.mjs

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Mise en cache des ressources

Astro stocke les images traitées dans un répertoire cache lors de la création du site, tant pour les images locales que pour les images distantes provenant de sources autorisées. En préservant le répertoire de cache entre les compilations, les ressources traitées sont réutilisées, ce qui améliore le temps de compilation et l’utilisation de la bande passante.

Le répertoire de cache par défaut est ./node_modules/.astro, mais il peut être modifié en utilisant le paramètre de configuration cacheDir.

Images distantes

Les images distantes dans le cache des ressources sont gérées en fonction de la mise en cache HTTP, et respectent l’en-tête Cache-Control renvoyé par le serveur distant. Les images sont mises en cache si l’en-tête Cache-Control le permet et seront utilisées jusqu’à ce qu’elles ne soient plus fraîches.

Revalidation

Ajouté à la version : astro@5.1.0

La revalidation réduit l’utilisation de la bande passante et le temps de compilation en vérifiant auprès du serveur distant si une image mise en cache qui a expiré est toujours d’actualité. Si le serveur indique que l’image est encore fraîche, la version mise en cache est réutilisée, sinon l’image est téléchargée à nouveau.

La revalidation nécessite que le serveur distant envoie des en-têtes Last-Modified et/ou Etag (étiquette d’entité) avec ses réponses. Cette fonction est disponible pour les serveurs distants qui prennent en charge les en-têtes If-Modified-Since et If-None-Match.

Intégrations communautaires

Il existe plusieurs intégrations d’images communautaires pour optimiser et travailler avec des images dans votre projet Astro.