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
Titre de la section Importations depuis astro:assetsimport { Image, Picture, getImage, inferRemoteSize, } from 'astro:assets';
<Image />
Titre de la section <Image />Le composant <Image />
optimise et transforme les images.
Ce composant peut également être utilisé pour créer des images adaptatives qui peuvent s’ajuster en fonction de la taille de leur conteneur ou de la taille et de la résolution de l’écran d’un appareil.
---// importe le composant Image et l'imageimport { 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."/>
Propriétés d’Image
Titre de la section Propriétés d’ImageLe 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<{ Par défault : 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 danssrc
: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';---<Imagesrc="/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';---<Imagesrc="https://example.com/image-distante.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.
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
Titre de la section densitiesType : (number | `${number}x`)[] | undefined
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 les images adaptatives utilisant une propriété 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.
---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"/>
Type : number[] | undefined
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 adaptatives à l’aide d’une propriété layout
. Fournir ces valeurs n’est généralement pas nécessaire, mais peut 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.
---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"/>
Type : string | undefined
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 adaptatives à l’aide d’une propriété layout
. Fournir ces valeurs n’est généralement pas nécessaire, mais peut 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.
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 qualityType : 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
et100
(interprété différemment selon les formats).
inferSize
Titre de la section inferSizeType : boolean
Par défaut : false
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.
priority
Titre de la section priorityType : boolean
Par défaut : false
astro@5.10.0
Nouveau
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.
---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.
<Picture />
Titre de la section <Picture />
Ajouté à la version :
astro@3.3.0
Le composant <Picture />
génère une image optimisée avec plusieurs formats et/ou tailles.
Ce composant peut également être utilisé pour créer des images adaptatives qui peuvent s’ajuster en fonction de la taille de leur conteneur ou de la taille et de la résolution de l’écran d’un appareil.
---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>
Propriétés de Picture
Titre de la section Propriétés de Picture<Picture />
accepte toutes les propriétés du composant <Image />
, y compris les propriétés d’image adaptatives, en plus des suivantes :
formats
Titre de la section formatsType : 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 fallbackFormatType : 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 pictureAttributesType : 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.
---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>
Propriétés des images adaptatives
Titre de la section Propriétés des images adaptativesLa définition de la propriété layout
sur un composant <Image />
ou <Picture />
crée une image adaptative et active des paramètres de propriété supplémentaires.
---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 automatiquement générés en fonction des dimensions de l’image et du type de mise en page. Le composant <Image />
précédent générera la sortie HTML suivante :
<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">
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 :
: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%;}
Vous pouvez remplacer les styles par défaut object-fit
et object-position
en définissant les props fit
et position
sur le composant <Image />
ou <Picture />
.
Type : 'constrained' | 'full-width' | 'fixed' | 'none'
Par défault : image.layout | 'none'
astro@5.10.0
Nouveau
Définit une image adaptative et détermine son redimensionnement lorsque son conteneur change de taille. Peut être utilisé pour remplacer la valeur par défaut configurée pour image.layout
.
-
constrained
- L’image sera réduite pour s’adapter au conteneur, en conservant son rapport hauteur/largeur, mais ne sera pas agrandie au-delà de la largeur (width
) et de la hauteur (height
) spécifiées, ou des dimensions d’origine de l’image.Utilisez cette option si vous souhaitez que l’image s’affiche à la taille souhaitée, si possible, mais qu’elle soit réduite pour s’adapter aux écrans plus petits. Cela correspond au comportement par défaut des images avec Tailwind. En cas de doute, c’est probablement la mise en page à choisir.
-
full-width
- L’image sera mise à l’échelle pour s’adapter à la largeur du conteneur, en conservant son rapport hauteur/largeur.Utilisez ceci pour les images de couverture ou d’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. Unsrcset
sera généré pour prendre en charge les affichages haute densité, mais pas pour les différentes tailles d’écran.Utilisez cette option si l’image ne peut pas être redimensionnée, par exemple des icônes ou des logos plus petits que la largeur de l’écran, ou d’autres images dans un conteneur à largeur fixe.
-
none
- L’image ne sera pas adaptative. Aucun attributsrcset
ousizes
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, avec la valeur « contraint » (constrained
) définie comme mise en page par défaut, vous pouvez remplacer la propriété layout
de n’importe quelle image individuelle :
---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" />
Type : 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
Par défault : image.objectFit | 'cover'
astro@5.10.0
Nouveau
Activé lorsque la propriété layout
est définie ou configurée. Définit comment une image adaptative doit être recadrée si son rapport hauteur/largeur est modifié.
Les valeurs correspondent à celles de la propriété CSS object-fit
. La valeur par défaut est cover
ou la valeur de image.objectFit
si elle est définie. Peut être utilisé pour remplacer les styles par défaut de object-fit
.
position
Titre de la section positionType : string
Par défault : image.objectPosition | 'center'
astro@5.10.0
Nouveau
Activé lorsque la propriété layout
est définie ou configurée. Définit la position du recadrage de l’image pour une image adaptative si le rapport hauteur/largeur est modifié.
Les valeurs correspondent à celles de la propriété CSS object-position
. La valeur par défaut est center
ou la valeur de image.objectPosition
si elle est définie. Peut être utilisé pour remplacer les styles par défaut de la propriété object-position
.
priority
Titre de la section priorityType : boolean
Par défault : false
astro@5.10.0
Nouveau
Activé lorsque la propriété layout
est définie ou configurée. Si défini, charge rapidement une image adaptative. Sinon, les images sont chargées en différé. Utilisez cette option pour votre plus grande image au-dessus de la ligne de flottaison. La valeur par défaut est false
.
getImage()
Titre de la section getImage()Type : (options: UnresolvedImageTransform) => Promise<GetImageResult>
getImage()
s’appuie sur des API serveur uniquement et interrompt la génération lorsqu’elle est utilisée sur le client.
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'>>
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");