Photo
À quoi il sert
Photo affiche une image importée localement, optimisée au build, avec sa place réservée avant chargement.
Quand l’utiliser
- Afficher une image locale : Astro la produit en AVIF et WebP, avec un repli JPEG ou PNG.
- Réserver la place de l’image avec width et height, pour éviter le décalage de la mise en page.
Quand ne pas l’utiliser
- Pour une URL distante : le composant refuse une chaîne et exige un import local.
- Pour une légende ou un crédit : utiliser Figure, qui enveloppe une image.
- Pour une galerie : utiliser Gallery, qui gère plusieurs images et leurs libellés.
Exemples
Image principale
Portrait recadré en haut
Décorative
Capture avec filet
---
import Photo from '@paulperigault/astro/Photo.astro';
import portrait from './portrait.jpg';
---
<Photo src={portrait} alt="Portrait recadré, visage au centre" ratio="portrait" focal="top" />Accessibilité
Clavier
- Photo ne rend aucun élément interactif : rien à atteindre au clavier.
- Le fond d’attente est masqué (aria-hidden="true", focusable="false") : il n’est pas focalisable.
Lecteur d’écran
- Le texte de l’attribut alt est lu comme nom de l’image.
- Avec decorative, alt="" : l’image est ignorée par les lecteurs d’écran.
- Le fond d’attente à la couleur dominante est masqué aux technologies d’assistance.
Garanti par le composant
- alt est obligatoire : une chaîne vide ou blanche lève une erreur au build.
- alt="" n’est posé qu’avec decorative, jamais par défaut.
- width et height sont toujours rendus.
- priority : loading="eager" et fetchpriority="high" ; sinon loading="lazy" et decoding="async".
- Aucun attribut style.
À la charge de l’intégrateur
- Décrire dans alt ce que l’image apporte : le composant ne vérifie pas le sens.
- Réserver priority à l’image principale, une seule par page.
- Choisir layout selon l’emplacement : il règle sizes et les largeurs générées.
- Entourer l’image d’un lien seulement si le lien a son propre nom accessible.
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
| alt | string | — | Texte alternatif : ce que l'image apporte au contenu. Vide : erreur au build. |
| decorative | true | — | Image purement décorative, rendue avec `alt=""`. Exclusif de `alt`. |
| src (obligatoire) | ImageMetadata | — | Image importée localement (`import photo from './photo.jpg'`). |
| ratio | "portrait" | "square" | "landscape" | "wide" | — | Proportion du cadre ; absente, l'image garde sa proportion propre. |
| focal | "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | 'center' | Point gardé visible quand le cadre recadre l'image. |
| priority | boolean | false | Image principale de la page (LCP) : chargée tout de suite, en priorité. |
| layout | "page" | "measure" | "half" | "third" | "avatar" | 'measure' | Emplacement dans la page ; règle `sizes` et les largeurs générées. |
| kind | "photo" | "capture" | "illustration" | 'photo' | Nature de l'image ; règle la qualité et le format de repli (JPEG pour une photo, PNG sinon). |
| rule | boolean | false | Filet autour du cadre (captures sur fond clair). |
| sizes | string | — | Remplace `sizes` déduit de `layout`, quand la hauteur borne l'image (dialogue). |
| class | string | — | Réservé au placement du composant dans son parent. |
Jetons utilisés
--pp-color-line--pp-color-media-placeholder--pp-media-radius--pp-media-rule--pp-ratio-landscape--pp-ratio-portrait--pp-ratio-square--pp-ratio-wide--pp-size-measure--pp-size-page--pp-space-3xl--pp-space-xl
Preuves et décisions
- WCAG 1.1.1 Contenu non textuel
- Core Web Vitals : CLS sous 0,1 (convention Google)
- LCP et CLS sur la page photo : apps/docs/e2e/media.spec.ts
- Tests : packages/astro/test/Photo.test.ts