Images
Astro vous propose plusieurs façons d’utiliser les 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 !
Où stocker les images
Titre de la section Où stocker les imagessrc/
vs public/
Titre de la section 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 construction 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. Les images peuvent être stockées dans n’importe quel dossier, y compris avec votre contenu.
Stockez vos images dans le dossier public/
si vous voulez éviter tout traitement ou avoir un lien public direct vers elles.
Images distantes
Titre de la section Images distantesVous 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).
Pour une protection supplémentaire lors du traitement de sources externes, les images distantes ne seront traitées qu’à partir des sources d’images autorisées spécifiées dans votre configuration. Cependant, toutes les images distantes peuvent être affichées.
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. Consultez nos guides CMS pour des exemples d’intégration de services communs.
Images dans les fichiers .astro
Titre de la section Images dans les fichiers .astroDans les fichiers .astro
, les images locales doivent être importées dans le fichier pour pouvoir être utilisées. Les images distantes et public/
n’ont pas besoin d’être importées.
Importez et utilisez le composant <Image />
intégré d’Astro pour les images optimisées en utilisant astro:assets
. Alternativement, la syntaxe Astro permet d’écrire une balise HTML <img>
directement, ce qui évite le traitement de l’image.
Pour importer dynamiquement des images depuis le dossier src/
, voir la recette suivante :
<Image />
(astro:assets
)
Titre de la section <Image /> (astro:assets)Utilisez le composant Astro intégré <Image />
pour afficher des versions optimisées de vos images locales et des images distantes configurées.
Les images du dossier public/
, ainsi que les images distantes qui ne sont pas spécifiquement configurées dans votre projet, peuvent également être utilisées avec le composant Image, mais elles ne seront pas traitées.
<Image />
peut transformer les dimensions, le type de fichier et la qualité d’une image locale ou d’une image distante autorisée afin de contrôler l’image affichée. La balise <img>
résultante inclut les attributs alt
, loading
et decoding
et déduit les dimensions de l’image pour éviter le Cumulative Layout Shift (CLS).
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
et la bonne hauteur
pour vos images locales.
Propriétés
Titre de la section Propriétéssrc (obligatoire)
Titre de la section src (obligatoire)Le format de la valeur src
de votre fichier image dépend de l’endroit où se trouve votre fichier image :
-
Images locales dans
src/
- vous devez aussi 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 valeursrc
: -
Images dans le dossier
public/
- utilisez le chemin de fichier de l’image par rapport au dossier public: -
Images distantes - utilisez l’URL complète de l’image** comme valeur de la propriété :
alt (obligatoire)
Titre de la section alt (obligatoire)Utilisez l’attribut obligatoire alt
pour fournir une chaîne de texte alternatif comme description 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.
Largeur et hauteur (nécessaires pour les images public/
et les images distantes)
Titre de la section Largeur et hauteur (nécessaires pour les images public/ et les images distantes)Ces propriétés définissent les dimensions à utiliser pour l’image.
Lors de l’utilisation d’images dans leur format d’origine, width
et height
sont optionnels. Ces dimensions peuvent être automatiquement déduites des fichiers images situés dans src/
et des images distantes avec inferSize
fixé à true
.
Cependant, ces deux propriétés sont nécessaires pour les images stockées dans votre dossier public/
car Astro n’est pas en mesure d’analyser ces fichiers.
Densités
Titre de la section Densités
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 le tag <img>
. Ne pas fournir de valeur pour widths
lors de l’utilisation de cette valeur.
Les densités qui sont égales à des largeurs plus grandes que l’image originale seront ignorées pour éviter d’augmenter l’échelle de l’image.
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 originale seront ignorées afin d’éviter une mise à l’échelle de l’image.
Vous pouvez optionnellement indiquer le type de fichier image à utiliser.
Par défaut, le composant <Image />
produira un fichier .webp
.
Qualité
Titre de la section Qualitéquality
est une propriété optionnelle qui peut être soit :
- un preset (
low
,mid
,high
,max
) qui est automatiquement normalisé entre les formats. - un nombre de
0
à100
(interprété différemment selon les formats).
inferSize
Titre de la section inferSize
Ajouté à la version :
astro@4.4.0
Permet de définir automatiquement la “largeur” et la “hauteur” originales d’une image distante.
Par défaut, cette valeur est fixée à false
et vous devez spécifier manuellement les deux dimensions pour votre image distante.
Ajoutez inferSize
au composant <Image />
(ou inferSize: true
à getImage()
) pour déduire ces valeurs du contenu de l’image lorsqu’elle est récupérée. Ceci est utile si vous ne connaissez pas les dimensions de l’image distante, ou si elles sont susceptibles de changer :
inferSize
peut récupérer les dimensions d’une image distante d’un domaine qui n’a pas été autorisé, mais l’image elle-même ne sera pas traitée.
Propriétés supplémentaires
Titre de la section Propriétés supplémentairesEn plus des propriétés ci-dessus, le composant <Image />
accepte toutes les propriétés acceptées par la balise HTML <img>
.
Par exemple, vous pouvez fournir une class
à l’élément final <img>
.
Définition des valeurs par défaut
Titre de la section Définition des valeurs par défautActuellement, il n’existe aucun moyen de spécifier des valeurs par défaut pour tous les composants <Image />
. Les attributs requis doivent être définis sur chaque composant individuel.
Comme alternative, vous pouvez envelopper ces composants dans un autre composant Astro pour les réutiliser. Par exemple, vous pouvez créer un composant pour les images de vos articles de blog :
<Picture />
Titre de la section <Picture />
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.
Propriétés
Titre de la section Propriétés<Picture />
accepte toutes les propriétés du composant <Image />
, plus les suivantes :
formats
Titre de la section formatsUn tableau de formats d’image à utiliser pour les balises <source>
. Les entrées seront ajoutées aux éléments <source>
dans l’ordre où elles sont listées, et cet ordre détermine le format qui sera affiché. Pour de meilleures performances, listez le format le plus moderne en premier (par exemple webp
ou avif
). Par défaut, cet ordre est fixé à ['webp']
.
fallbackFormat
Titre de la section fallbackFormatFormat à utiliser comme valeur de remplacement pour la balise <img>
.
La valeur par défaut est .png
pour les images statiques (ou .jpg
si l’image est un JPG), .gif
pour les images animées, et .svg
pour les fichiers SVG.
pictureAttributes
Titre de la section pictureAttributesUn objet d’attributs à ajouter à la balise <picture>
.
Utilisez cette propriété pour appliquer des attributs à l’élément extérieur <picture>
lui-même. Les attributs appliqués au composant <Picture />
directement s’appliqueront à l’élément <img>
intérieur, à l’exception de ceux utilisés pour la transformation de l’image.
La syntaxe Astro permet également d’écrire une balise <img>
directement, avec un contrôle total sur sa sortie finale. Ces images ne seront pas traitées et optimisées.
Elle accepte toutes les propriétés de la balise HTML <img>
, et la seule propriété requise est src
.
Images locales dans src/
Titre de la section Images locales dans src/Les images locales doivent être importées à partir du chemin relatif du fichier .astro
existant, ou configurer et utiliser un [alias d’importation]](/fr/guides/imports/#alias). Ensuite, vous pouvez accéder au src
de l’image et à d’autres propriétés à utiliser dans la balise <img>
.
Par exemple, utilisez les propriétés height
et width
de l’image pour éviter le CLS et améliorer Core Web Vitals.
Les images importées correspondent à la signature suivante :
Images dans public/
Titre de la section Images dans public/Pour les images situées dans public/
, utilisez le chemin du fichier de l’image relatif au dossier public comme valeur src
:
Images distantes
Titre de la section Images distantesPour les images distantes, utilisez l’URL complète de l’image comme valeur src
:
Choisir <Image />
vs <img>
Titre de la section Choisir <Image /> vs <img>Le composant <Image />
optimise votre image et déduit la largeur et la hauteur (des images locales) en se basant sur le rapport d’aspect original afin d’éviter le CLS.
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 à l’attribut
src
et de le modifier dynamiquement côté client
Autoriser les images distantes
Titre de la section Autoriser les images distantesVous pouvez configurer des listes de domaines d’URL de sources d’images autorisées et des modèles pour l’optimisation des images en utilisant image.domains
et image.remotePatterns
. Cette configuration est une couche de sécurité supplémentaire pour protéger votre site lorsqu’il affiche des 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 cumulatif de la mise en page (CLS).
Par exemple, la configuration suivante permet d’optimiser seulement les images distantes provenant de astro.build
:
La configuration suivante n’autorise que les images distantes provenant d’hôtes HTTPS :
Utilisation d’images provenant d’un CMS ou d’un CDN
Titre de la section Utilisation d’images provenant d’un CMS ou d’un CDNLes 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, si le CDN fournit un SDK Node.js, vous pouvez l’utiliser dans votre projet. Par exemple, Cloudinary’s SDK peut générer une balise <img>
avec le src
approprié pour vous.
Images dans les fichiers Markdown
Titre de la section Images dans les fichiers MarkdownUtilisez la syntaxe Markdown standard ![alt](src)
dans vos fichiers .md
. Cette syntaxe fonctionne avec le Service API image d’Astro pour optimiser vos images locales et les images distantes autorisées.
La balise <img>
n’est pas supportée pour les images locales, et le composant <Image />
n’est pas disponible dans les fichiers .md
.
Si vous avez besoin de plus de contrôle sur les attributs de vos images, nous vous recommandons d’utiliser le format de fichier .mdx
, qui vous permet d’inclure le composant <Image />
d’Astro ou une balise JSX <img />
en plus de la syntaxe Markdown. Utilisez l’intégration MDX pour ajouter la prise en charge de MDX à Astro.
Images dans les fichiers MDX
Titre de la section Images dans les fichiers MDXVous pouvez utiliser le composant <Image />
d’Astro et les balises JSX <img />
dans vos fichiers .mdx
en important à la fois le composant et votre image. Utilisez-les telles quelles dans les fichiers .astro
.
De plus, il y a un support pour la syntaxe standard Markdown ![alt](src)
sans importation nécessaire
Images dans les collections de contenus
Titre de la section Images dans les collections de contenusLes images dans les collections de contenus seront traitées de la même manière que dans Markdown et MDX selon le type de fichier que vous utilisez.
En outre, vous pouvez déclarer une image associée à une entrée de la collection de contenus, telle que l’image de couverture d’un article de blog, dans votre frontmatter en utilisant son chemin d’accès relatif au dossier courant :
L’aide image
pour le schéma des collections de contenu vous permet de valider les métadonnées de l’image en utilisant Zod.
L’image sera importée et transformée en métadonnées, vous permettant de la passer comme src
à <Image/>
, <img>
, ou getImage()
.
L’exemple ci-dessous montre une page d’index de blog qui rend la photo de couverture et le titre de chaque article de blog à partir du schéma ci-dessus :
Images dans les composants framework UI
Titre de la section Images dans les composants framework UILors de l’ajout d’images dans un composant UI utilisez la syntaxe d’image propre au composant pour rendre une image (par exemple, <img />
en JSX, <img>
en Svelte).
Les images locales doivent d’abord être importées pour accéder à leurs propriétés d’image telles que src
Transmission du composant Image
Titre de la section Transmission du composant ImageLe composant <Image />
, comme tout autre composant Astro, n’est pas disponible pour les composants de l’interface utilisateur.
Mais vous pouvez passer le contenu statique généré par <Image />
à un composant framework à l’intérieur d’un fichier .astro
en tant qu’enfant ou en utilisant un nommé <slot/>
:
Générer des images avec getImage()
Titre de la section Générer des images avec getImage()getImage()
s’appuie sur des API réservées au serveur et interrompt la construction lorsqu’il est utilisé sur le client.
La fonction getImage()
est destinée à générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une API Route. Il 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 (sauf alt
).
Il renvoie un objet avec les propriétés suivantes :
Alt Text
Titre de la section Alt TextTous 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
Titre de la section Service d’images par défautSharp 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
.
Lorsque vous utilisez un gestionnaire de paquet strict comme pnpm
, vous pouvez avoir besoin d’installer manuellement Sharp dans votre projet même si c’est une dépendance d’Astro :
Configurer Squoosh
Titre de la section Configurer SquooshSi vous préférez utiliser Squoosh pour transformer vos images, mettez à jour votre configuration avec ce qui suit :
Configurer le service no-op passthrough
Titre de la section Configurer le service no-op passthroughSi votre adaptateur pour le mode serveur' ou
hybride’ ne supporte pas l’optimisation d’image Squoosh et Sharp intégrée à Astro (par exemple Deno, Cloudflare), vous pouvez configurer un service d’image no-op 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 Squoosh et Sharp :
Intégrations communautaires
Titre de la section Intégrations communautairesIl existe plusieurs intégrations d’images communautaires pour optimiser et travailler avec des images dans votre projet Astro.
Learn