Thanks to visit codestin.com
Credit goes to developer.mozilla.org

Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

<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

html
<details open>
  <summary>Détails produit</summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 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

html
<details open>
  <summary><h4>Détails produit</h4></summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 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

html
<details open>
  <summary><strong>Détails</strong></summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 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.

css
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

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&nbsp;; 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&nbsp;; 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

Voir aussi