Images

Astro fournit plusieurs façons d’utiliser les images sur votre site, qu’elles soient stockées localement dans votre projet, liées à distance ou stockées dans un CMS ou un CDN !

Astro utilise les éléments HTML <img> pour afficher les images, et tous les attributs HTML des images sont supportés.

L’attribut src est requis, et son format va dépendre de l’endroit où les images sont situées :

---
import rocket from '../images/rocket.svg';
---
<!-- Image distante sur un autre serveur -->
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro">
<!-- Image locale située à public/assets/stars.png -->
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé.">
<!-- Image locale située à src/images/rocket.svg -->
<img src={rocket} alt="Une fusée dans l'espace."/>

Vous pouvez utiliser la syntaxe Markdown standard ![]() ou les balises HTML standard <img> dans vos fichiers .md pour les images situées dans votre dossier public/, ou pour les images distantes sur un autre serveur.

Si vous ne pouvez pas garder vos images dans public/, nous vous recommandons d’utiliser le format de fichier .mdx, qui vous permet de combiner des composants importés avec une syntaxe semblable à celle de Markdown. Utilisez l’intégration MDX (EN) pour ajouter le support de MDX à Astro.

# Ma Page Markdown

<!-- Image locale située à public/assets/stars.png -->
![Un ciel nocturne étoilé.](/assets/stars.png)
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé.">

<!-- Image distante sur un autre serveur -->
![Astro](https://astro.build/assets/logo.png)
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro">

Vous pouvez utiliser la syntaxe Markdown standard ![]() ou les balises JSX <img /> dans vos fichiers .mdx pour afficher des images depuis votre dossier public/ ou depuis un serveur distant.

De plus, vous pouvez importer et utiliser des images situées dans votre répertoire de projet src/, comme vous le feriez dans des composants Astro.

import rocket from '../images/rocket.svg';

# Ma Page MDX

// Image locale située à src/images/rocket.svg
<img src={rocket} alt="Une fusée dans l'espace."/>

// Image locale située à public/assets/stars.png
![Un ciel nocturne étoilé.](/assets/stars.png)
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé." />

// Image distante sur un autre serveur
![Astro](https://astro.build/assets/logo.png)
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro" />

Lorsque vous ajoutez des images dans un composant de Framework UI (ex : React, Svelte), utilisez la syntaxe des images appropriée pour ce Framework de composants particulier.

Vos images stockées dans src/ peuvent être utilisées par les composants (.astro, .mdx et autres Frameworks UI) mais pas dans les fichiers Markdown.

Nous recommandons de garder vos images dans public/ ou de les stocker à distance si vous devez utiliser des fichiers Markdown.

Importez-les depuis un chemin de fichier relatif ou un alias d’import dans n’importe quel fichier composant et utilisez ensuite l’import comme attribut src de l’image.

---
// Accéder aux images dans `src/images/`
import logo from '../images/logo.png';
---
<img src={logo} width="40" alt="Astro" />

Vos images stockées dans public/ peuvent être utilisées par les composants (.astro, .mdx et autres Frameworks UI) mais aussi dans les fichiers Markdown.

Cependant les fichiers dans le répertoire /public sont toujours utilisés ou copiés tels quels, sans aucun traitement. Si vous utilisez des images en dehors des fichiers Markdown, nous vous recommandons de les conserver dans le dossier src lorsque cela est possible afin qu’Astro puisse les transformer, les optimiser et les regrouper.

L’attribut src est relatif au dossier public. Dans Markdown, vous pouvez aussi utiliser la notation ![]().

---
// Accéder aux images dans `public/images/`
---
<img src="/images/logo.png" />

L’intégration officielle d’Astro des images fournit deux composants Astro différents pour rendre des images optimisées, <Image /> et <Picture />. Celle-ci est supportée pour tous les sites statiques et pour certains hébergeurs de déploiement rendu côté serveur (EN).

Après avoir installé @astrojs/image (EN), vous pouvez utiliser ces deux composants partout où vous pouvez utiliser des composants Astro : dans les fichiers .astro et .mdx.

Le composant Astro <Image /> (EN) vous permet d’optimiser une seule image et de spécifier sa largeur, hauteur, et/ou son rapport rapport largeur/hauteur. Vous pouvez même convertir votre image dans un format de sortie particulier.

Ce composant est utile pour les images qui doivent conserver une taille constante sur tous les écrans ou pour contrôler étroitement la qualité d’une image (ex : les logos).

Pour les images responsive, ou pour une direction artistique, utilisez plutôt le composant <Picture />.

(attributs requis : src (EN), alt (EN), format (EN), et dimensions)

Passez une URL complète à l’attribut src du composant <Image /> et incluez une valeur pour alt.

Le composant <Image /> ne peut pas déterminer le format de fichier d’origine d’une image distante, vous devez donc fournir un format de sortie (ex : png, avif) pour convertir votre image distante.

Vous devez également fournir soit width (EN) et height (EN), soit l’une des dimensions et un aspectRatio (EN) pour éviter les décalages de mise en page du contenu car le composant <Image /> ne connaît pas les dimensions d’une image distante.

Toutes les autres propriétés (EN) sont facultatives.

(attributs requis : src (EN), et alt (EN))

Importez votre image dans le Frontmatter et passez-la directement à l’attribut src du composant <Image />.

alt est requis, mais toutes les autres propriétés (EN) sont facultatives et, si elles ne sont pas fournies, prendront par défaut les propriétés d’origine du fichier image.

(attributs requis : src (EN), alt (EN), format (EN), et dimensions)

Passez un chemin relatif au répertoire public à l’attribut src du composant <Image /> et incluez une valeur pour alt.

Elle sera traitée comme une image distante, ce qui nécessite à la fois width (EN) et height (EN), ou une dimension et un attribut aspectRatio (EN).

Une valeur pour l’attribut format (ex : png, avif) est requise afin de transformer votre image.

Toutes les autres propriétés (EN) sont facultatives.

Votre image d’origine sera copiée sans traitement dans le dossier de Build, comme tous les fichiers situés dans public/, et l’intégration d’image d’Astro renverra également des versions optimisées de l’image.

---
import { Image } from '@astrojs/image/components';
import localImage from "../assets/logo.png";
const remoteImage = "https://picsum.photos/id/957/300/200.jpg";
const localAlt = "Le logo d'Astro";
const remoteAlt = "Une vue en contre-plongée d'une forêt pendant la journée";
---

<!-- Image locale optimisée, gardant la largeur, la hauteur et le format d'image d'origine -->
<Image src={localImage} alt={localAlt} />

<!-- La hauteur sera recalculée pour correspondre au ratio d'aspect original -->
<Image src={localImage} width={300} alt={localAlt} />

<!-- Pour les images distantes, les dimensions désirées et le format sont requis -->
<Image src={remoteImage} width={300} aspectRatio="1:1" format="png" alt={remoteAlt} />

<!-- recadrage à une largeur et une hauteur spécifiques -->
<Image src={localImage} width={300} height={600} alt={localAlt}/>
<Image src={remoteImage} width={544} height={184} format="png" alt={remoteAlt}/>

<!-- recadrage à un ratio d'aspect spécifique et conversion vers un format AVIF -->
<Image src={localImage} aspectRatio="16:9" format="avif" alt={localAlt}/>
<Image src={remoteImage} height={200} aspectRatio="16:9" format="avif" alt={remoteAlt}/>

<!-- les importations d'images locales peuvent également être directement intégrées -->
<Image src={import('../assets/logo.png')} alt={localAlt}/>

<!-- Si une image est située dans le dossier `/public`, utilisez son chemin relatif à `/public` -->
<Image src="/penguin.jpg" width="300" aspectRatio={1} format="png" alt="A happy penguin"/>

Le composant Astro <Picture /> (EN) peut être utilisé pour fournir des images responsive sur votre site, y compris plusieurs tailles, formats et mises en page d’image.

Vous pouvez laisser le navigateur de l’utilisateur choisir les tailles d’image, les résolutions et les types de fichiers appropriés en fonction de facteurs tels que la taille d’écran et la bande passante. Ou alors, vous pouvez spécifier des règles que le navigateur doit suivre en fonction des media queries.

Ce composant est utile pour optimiser ce que votre utilisateur voit à différentes tailles d’écran, ou pour la direction artistique.

(attributs requis : src (EN), widths (EN), sizes (EN), alt (EN), et aspectRatio (EN))

Passez une URL complète à l’attribut src du composant <Picture />.

Une valeur pour aspectRatio est également requise pour s’assurer que la hauteur correcte des images distantes puisse être calculée au moment du Build.

Vous devez fournir au composant des indications sur les largeurs d’image et les tailles d’écran, mais toutes les autres propriétés (EN) sont facultatives.

Bien que formats (EN) ne soit pas requis, le format d’image d’origine des images distantes est inconnu et ne sera pas inclus par défaut. S’il n’est pas fourni, seuls webp et avif seront inclus.

(attributs requis : src (EN), widths (EN), sizes (EN), alt (EN))

Importez votre image dans Frontmatter et passez-la directement à l’attribut src du composant <Picture />.

Vous devez fournir au composant des indications sur les largeurs d’image et les tailles d’écran, mais toutes les autres propriétés (EN) sont facultatives.

Par défaut, les formats (EN) du composant <Picture /> incluront avif et webp en plus du format d’origine de l’image s’il n’est pas spécifié.

(attributs requis : src (EN), widths (EN), sizes (EN), alt (EN), et aspectRatio (EN))

Passez à l’attribut src du composant un chemin relatif au dossier public et incluez une valeur pour alt.

L’image sera traitée comme une image distante, donc une valeur pour aspectRatio est également requise pour s’assurer que la hauteur puisse être correctement calculée au moment du Build.

Vous devez fournir au composant des indications sur les largeurs d’image et les tailles d’écran, mais toutes les autres propriétés (EN) sont facultatives.

Bien que formats (EN) ne soit pas requis, le format d’origine des images dans le dossier public/ est inconnu et ne sera pas inclus par défaut. S’il n’est pas fourni, seuls “webp” et “avif” seront inclus.

Votre image d’origine sera copiée sans traitement dans le dossier de Build, comme tous les fichiers situés dans public/, et l’intégration d’image d’Astro renverra également des versions optimisées de l’image.

---
import { Picture } from '@astrojs/image/components';
import localImage from '../assets/logo.png';
const remoteImage = 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png';
---

<!-- Image locale avec plusieurs tailles et formats -->
<Picture src={localImage} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" formats={['avif', 'jpeg', 'png', 'webp']} alt="The Astro logo" />

<!-- Image distante (le rapport d'aspect est requis) -->
<Picture src={remoteImage} widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

<!-- Les images dans /public fonctionnent comme les images distantes -->
<Picture src="/logo.png" widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

<!-- Les imports directs sont supportés -->
<Picture src={import("../assets/logo.png")} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

Dans les fichiers .mdx, <Image /> et <Picture /> peuvent recevoir votre src de l’image via des imports et exports.

import { Image, Picture } from '@astrojs/image/components';
import rocket from '../assets/rocket.png';
export const galaxy = 'https://astro.build/assets/galaxy.jpg';

<Image src={import('../assets/logo.png')} alt="Astro"/>
<Image src={rocket} width={300} alt="Fusée approchant la lune."/>
<Picture src={rocket} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="Une fusée qui décolle." />
<Picture src={galaxy} widths={[200, 400, 800]} aspectRatio={16/9} sizes="(max-width: 800px) 100vw, 800px" alt="Le cosmos." />

Actuellement, il n’existe aucun moyen de spécifier des valeurs par défaut pour tous les composants <Image /> et <Picture />. Les attributs requis doivent être définis sur chaque composant.

Comme alternative, vous pouvez encapsuler ces composants dans un autre composant Astro pour les réutiliser. Par exemple, vous pouvez créer un composant pour les images de votre article de blog :

---
import { Picture } from '@astrojs/image/components';

const {src, ...attrs} = Astro.props;
---
<Picture src={src} widths={[400, 800, 1500]} sizes="(max-width: 767px) 100vw, 736px" {...attrs} />

<style>
  img, picture :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

L’intégration d’image officielle modifiera les importations d’images pour renvoyer un objet plutôt qu’une chaîne de caractères source. L’objet possède les propriétés suivantes, dérivées du fichier importé :

{
  src: string;
  width: number;
  height: number;
  format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp';
}

Si l’intégration d’image est installée, reportez-vous à la propriété src de l’objet lors de l’utilisation de <img>.

---
import rocket from '../images/rocket.svg';
---
<img src={rocket.src} alt="Une fusée dans l'espace."/>

Une alternative consiste à ajouter ?url à vos imports pour leur dire de renvoyer une chaîne de caractères source.

---
import rocket from '../images/rocket.svg?url';
---
<img src={rocket} alt="Une fusée dans l'espace."/>

Les CDN d’images fonctionnent avec Astro. Utilisez l’URL complète d’une image comme attribut src dans une balise <img> ou une notation Markdown.

Alternativement, si le CDN fournit un SDK Node.js, vous pouvez l’utiliser dans votre projet. Par exemple, le SDK de Cloudinary peut générer la balise <img> avec le src approprié pour vous.

Pour utiliser des images externes avec les composants <Image /> et <Picture /> de l’intégration d’image d’Astro, vous devez spécifier les valeurs de dimension et de format pour travailler avec des images distantes.

Tous les utilisateurs ne peuvent pas voir 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 /> de l’intégration d’image. Ces composants génèrent une erreur si aucun texte alternatif n’est fourni.

Si l’image est simplement décorative (i.e. elle ne contribue pas à la compréhension de la page), définissez alt="" pour que les lecteurs d’écran sachent ignorer l’image.

En plus de l’intégration @astrojs/image (EN) officielle, il existe plusieurs intégrations d’images communautaires pour optimiser et travailler avec des images dans votre projet Astro.