<summary> : l'élément de révélation d'un résumé
Baseline
Widely available
*
This feature is well established and works across many devices and browser versions. It’s been available across browsers since janvier 2020.
* Some parts of this feature may have varying levels of support.
L'élément HTML <summary>
représente une boîte permettant de révéler le contenu d'un résumé ou d'une légende pour le contenu d'un élément <details>
. En cliquant sur l'élément <summary>
, on passe de l'état affiché à l'état masqué (et vice versa) de l'élément <details>
parent.
Exemple interactif
<details>
<summary>
J'ai des clés mais pas de portes. J'ai de l'espace mais pas de pièce. Vous
pouvez entrer mais ne pouvez pas sortir. Qui suis-je ?
</summary>
Un clavier.
</details>
details {
border: 1px solid #aaa;
border-radius: 4px;
padding: 0.5em 0.5em 0;
}
summary {
font-weight: bold;
margin: -0.5em -0.5em 0;
padding: 0.5em;
}
details[open] {
padding: 0.5em;
}
details[open] summary {
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
Attributs
Cet élément inclut uniquement les attributs universels.
Notes d'utilisation
Un élément <summary>
peut contenir des éléments de titre, du texte simple ou tout contenu HTML pouvant être placé au sein d'un paragraphe.
Un élément <summary>
peut uniquement être utilisé comme le premier élément fils d'un élément <details>
. Lorsque l'utilisateur clique sur le résumé, l'élément <details>
parent change d'état (affiché ou masqué) et un évènement toggle
est envoyé à l'élément <details>
(ce qui permet de détecter un changement d'état via un script).
Le contenu de l'élément <details>
fournit la description accessible pour l'élément <summary>
.
Libellé par défaut
Si le premier enfant d'un élément <details>
n'est pas un élément <summary>
, l'agent utilisateur utilisera une chaîne de caractères par défaut (généralement « Détails ») comme libellé pour la boîte de révélation.
Mise en forme par défaut
Conformément à la spécification HTML, le style par défaut pour les éléments <summary>
inclut display: list-item
. Cela permet de changer ou de supprimer l'icône affichée comme widget à côté du libellé, qui est généralement un triangle.
Vous pouvez aussi changer le style en display: block
pour supprimer le triangle.
Voir la section Compatibilité des navigateurs pour plus de détails, car tous les navigateurs ne prennent pas encore en charge toutes les fonctionnalités de cet élément.
Pour les navigateurs basés sur WebKit, comme Safari, il est possible de contrôler l'affichage de l'icône via le pseudo-élément CSS non standard ::-webkit-details-marker
. Pour supprimer le triangle, utilisez summary::-webkit-details-marker { display: none }
.
Exemples
Voici quelques exemples montrant l'utilisation de <summary>
. Vous pouvez trouver d'autres exemples dans la documentation de l'élément <details>
.
Exemple simple
Un exemple simple montrant l'utilisation de <summary>
dans un élément <details>
:
HTML
<details open>
<summary>Détails produit</summary>
<ol>
<li>Date de fabrication : 01 janvier 2018</li>
<li>Numéro de lot : LMA2542501</li>
<li>Date limite de consommation : 31 août 2018</li>
</ol>
</details>
Résultat
Utilisation de titres
Il est possible d'utiliser des titres au sein d'un résumé.
HTML
<details open>
<summary><h4>Détails produit</h4></summary>
<ol>
<li>Date de fabrication : 01 janvier 2018</li>
<li>Numéro de lot : LMA2542501</li>
<li>Date limite de consommation : 31 août 2018</li>
</ol>
</details>
Résultat
Il existe actuellement quelques problèmes d'espacement qui peuvent être corrigés à l'aide de CSS.
Attention :
Le rôle attribué à l'élément <summary>
varie selon les navigateurs. Certains lui attribuent encore par défaut le rôle button
, ce qui supprime tous les rôles de ses enfants. Cette incohérence peut poser des problèmes aux utilisateur·ice·s de technologies d'assistance telles que les lecteurs d'écran (<h4>
dans l'exemple précédent verra son rôle supprimé et ne sera pas traité comme un titre pour ces utilisateur·ice·s). Vous devez tester votre implémentation de <summary>
sur plusieurs plateformes afin de garantir une prise en charge de l'accessibilité cohérente.
Utiliser des éléments HTML dans un résumé
Cet exemple ajoute une certaine sémantique à l'élément <summary>
pour indiquer que le libellé est important :
HTML
<details open>
<summary><strong>Détails</strong></summary>
<ol>
<li>Date de fabrication : 01 janvier 2018</li>
<li>Numéro de lot : LMA2542501</li>
<li>Date limite de consommation : 31 août 2018</li>
</ol>
</details>
Résultat
Changer l'icône du résumé
Le marqueur de l'élément <summary>
, c'est-à-dire le triangle de révélation, peut être personnalisé avec CSS. Le marqueur peut être ciblé à l'aide du pseudo-élément ::marker
, qui accepte la propriété abrégée list-style
ainsi que ses propriétés détaillées, comme list-style-type
. Cela permet de remplacer le triangle par une image (généralement avec list-style-image
) ou une chaîne de caractères (y compris des émojis). Dans cet exemple, nous remplaçons le contenu d'un widget de révélation et supprimons l'icône d'un autre en appliquant list-style: none
avant d'ajouter une icône personnalisée via du contenu généré.
CSS
Dans le premier widget de révélation, nous mettons en forme le ::marker
, en modifiant la propriété content
selon l'attribut [open]
de l'élément <details>
. Pour le second widget, nous supprimons le marqueur avec les propriétés list-style
, puis nous ajoutons un contenu généré stylisé avec le pseudo-élément ::after
. Nous incluons également des styles pour ::-webkit-details-marker
afin de cibler Safari. Le sélecteur pour le pseudo-élément spécifique au navigateur est inclus dans une pseudo-classe :is()
afin de ne pas invalider la liste des sélecteurs.
details {
font-size: 1rem;
font-family: "Open Sans", Calibri, sans-serif;
border: solid;
padding: 2px 6px;
margin-bottom: 1em;
}
details:first-of-type summary::marker,
:is(::-webkit-details-marker) {
content: "+ ";
font-family: monospace;
color: red;
font-weight: bold;
}
details[open]:first-of-type summary::marker {
content: "− ";
}
details:last-of-type summary {
list-style: none;
&::after {
content: "+";
color: white;
background-color: darkgreen;
border-radius: 1em;
font-weight: bold;
padding: 0 5px;
margin-inline-start: 5px;
}
[open] &::after {
content: "−";
}
}
details:last-of-type summary::-webkit-details-marker {
display: none;
}
Le CSS inclut le sélecteur d'attribut [open]
, qui ne correspond que lorsque l'attribut open
est présent (c'est-à-dire lorsque l'élément <details>
est ouvert). Les pseudo-classes :first-of-type
et :last-of-type
ciblent respectivement le premier et le dernier élément du même type. Nous avons inclus le pseudo-élément préfixé -webkit-
dans une pseudo-classe :is()
car elle accepte une liste de sélecteurs tolérante : si le pseudo-élément préfixé est invalide dans un navigateur, tout le bloc de sélecteurs ne sera pas invalidé. Nous avons aussi utilisé la syntaxe imbriquée de CSS. Voir le module Sélecteurs CSS.
HTML
<h1>Citations d'Helen Keller</h1>
<details>
<summary>Sur les droits des femmes</summary>
<p>
<q>Nous avons prié, nous avons supplié, nous avons imploré pour obtenir le droit de vote, dans l'espoir que les hommes, par chevalerie, accorderaient l'égalité des droits aux femmes et les associeraient aux affaires de l'État. Nous espérions que leur bon sens l'emporterait sur les préjugés et la stupidité. Nous pensions que leur sens tant vanté de la justice surmonterait les erreurs qui entravent si souvent l'esprit humain ; mais nous sommes toujours reparties les mains vides. Nous ne supplierons plus.</q>
</p>
</details>
<details>
<summary>Sur l'optimisme</summary>
<p>
<q>L'optimisme est la foi qui mène à la réussite ; rien ne peut être accompli sans espoir.</q>
</p>
</details>
Résultat
Résumé technique
Contenu autorisé | Contenu phrasé ou un élément décrivant du contenu de titre. |
---|---|
Omission de balises | Aucune, la balise ouvrante et la balise fermante sont obligatoires. |
Parents autorisés | Un élément <details> . |
Rôle ARIA implicite | Aucun rôle correspondant (angl.). |
Rôles ARIA autorisés | Aucun role autorisé. |
Interface DOM | HTMLElement |
Spécifications
Specification |
---|
HTML> # the-summary-element> |
Compatibilité des navigateurs
Loading…