Gallery
À quoi il sert
Gallery range des images en une, deux ou trois colonnes selon la largeur de son conteneur.
Quand l’utiliser
- Présenter plusieurs images d’une même série, chacune avec son texte alternatif.
- Agrandir chaque vignette dans un dialogue natif avec enlarge et labels.
Quand ne pas l’utiliser
- Pour une seule image : utiliser Photo, ou Figure si l’image a une légende.
- Pour un agrandissement sur un navigateur sans Invoker Commands : poser InvokerFallback.
Exemples
Grille simple
Agrandissement
<Gallery
id="galerie"
items={[{ src: photo, alt: 'Description de l’image' }]}
enlarge
labels={{ open: 'Agrandir', close: 'Fermer' }}
/>Accessibilité
Clavier
- Chaque vignette agrandie est un bouton natif : Tab l’atteint, Entrée ouvre le dialogue.
- Échap ferme le dialogue, et le focus revient sur la vignette.
Lecteur d’écran
- role="list" garde la sémantique de liste, même sans puces.
- Le bouton porte « Agrandir : » suivi de l’alt ; le dialogue est nommé par l’alt.
Garanti par le composant
- Grille en container queries, sans JavaScript : une, deux puis trois colonnes.
- Dialogue natif modal, fermé par son bouton, par Échap ou par clic hors de la boîte.
- Vignette agrandie d’une cible d’au moins --pp-size-target-min.
À la charge de l’intégrateur
- Fournir les libellés labels.open et labels.close, traduits par le site.
- Écrire un alt par image : Gallery ne le génère pas.
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
| id (obligatoire) | string | — | Préfixe des identifiants des dialogues. |
| items (obligatoire) | GalleryItem[] | — | Images : `{ src, alt, caption? }` ; l'alternative est obligatoire. |
| ratio | "portrait" | "square" | "landscape" | "wide" | 'square' | Proportion des vignettes. |
| enlarge | boolean | — | Chaque vignette ouvre l'image entière dans un dialogue natif. |
| labels | GalleryLabels | — | Libellés `{ open, close }` des boutons d'agrandissement, fournis par le site. |
Jetons utilisés
--pp-color-bg--pp-color-control--pp-color-fg--pp-color-line--pp-color-muted--pp-media-radius--pp-radius-control--pp-radius-surface--pp-size-control-height--pp-size-measure--pp-size-rule--pp-size-target-min--pp-space-3xl--pp-space-m--pp-space-s--pp-space-xs
Preuves et décisions
- WCAG 2.1.1 Clavier (A)
- WCAG 2.5.8 Taille de la cible (minimum) (AA)
- WCAG 4.1.2 Nom, rôle, valeur (A)
- Tests : apps/docs/e2e/gallery.spec.ts (clavier, axe)
- Tests : apps/docs/e2e/matrix/targets.spec.ts
- Tests : packages/astro/test/Gallery.test.ts