Aller au contenu
v5-beta

Référence de l'API 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 d’images.

Importations depuis astro:assets

Titre de la section Importations depuis astro:assets
import {
  Image,
  Picture,
  getImage,
  inferRemoteSize,
 } from 'astro:assets';

<Image />

Titre de la section &lt;Image /&gt;
src/components/MyComponent.astro
---
// importe le composant Image et l'image
import { Image } from 'astro:assets';
import myImage from "../assets/mon_image.png"; // Image a une résolution de 1600x900
---


<!-- `alt` est obligatoire sur le composant Image -->
<Image src={myImage} 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."
/>

Propriétés d’Image

Titre de la section Propriétés d’Image

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

src (obligatoire)
Titre de la section 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 myImportedImage from '../assets/my-local-image.png';
    ---
    <Image src={myImportedImage} 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/my-public-image.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/remote-image.jpg"
      alt="texte descriptif"
      width="200"
      height="150"
    />
alt (obligatoire)
Titre de la section 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 (obligatoire pour les images dans public/)
Titre de la section width et height (obligatoire pour les images dans public/)

Type : number | undefined

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

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
Titre de la section 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.

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/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image
  src={myImage}
  width={myImage.width / 2}
  densities={[1.5, 2]}
  alt="Une description de mon image."
/>
<!-- Sortie -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="Une description de mon image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
widths
Titre de la section 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.

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.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // La résolution de l'image est de 1600x900
---
<Image
  src={myImage}
  widths={[240, 540, 720, myImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
  alt="A description of my image."
/>
<!-- Sortie -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
    /_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="A description of my image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
format
Titre de la section 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
Titre de la section 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
Titre de la section inferSize

Type : boolean

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 :

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

inferSize peut récupérer les dimensions d’une image distante d’un domaine qui n’a pas été autorisé, , cependant l’image elle-même restera non traitée.

<Picture />

Titre de la section &lt;Picture /&gt;

Ajouté à la version : astro@3.3.0

Utilisez le composant Astro intégré <Picture /> pour afficher une image réactive avec plusieurs formats et/ou tailles.

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


<!-- `alt` est obligatoire sur le composant Picture -->
<Picture src={myImage} 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>

Propriétés de Picture

Titre de la section Propriétés de Picture

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

formats
Titre de la section 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
Titre de la section 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
Titre de la section 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/MyComponent.astro
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // La résolution de l'image est de 1600x900
---


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

getImage()

Titre de la section getImage()

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

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é.

getImage() prend un objet d’options avec les mêmes propriétés que le composant Image (à l’exception de alt).

---
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});`}></div>

Elle renvoie un objet avec le type suivant :

type GetImageResult = {
  /* Attributs HTML supplémentaires nécessaires au rendu de l'image (largeur, hauteur, style, etc.) */
  attributes: Record<string, any>;
  /* Paramètres passés validés */
  options: ImageTransform;
  /* Paramètres d'origine transmis */
  rawOptions: ImageTransform;
  /* Chemin d'accès à l'image générée */
  src: string;
  srcSet: {
    /* Valeurs générées pour srcset, chaque entrée a une URL et un descripteur de taille */
    values: SrcSetValue[];
    /* Une valeur prête à être utilisée dans l'attribut `srcset` */
    attribute: string;
  };
}

inferRemoteSize()

Titre de la section inferRemoteSize()

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

Ajouté à la version : astro@4.12.0

Une fonction permettant de déduire les dimensions des images distantes. 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");
Contribuer

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Le moyen le plus rapide d'alerter notre équipe d'un problème.

Communauté