Balise HTML <summary>

La balise <summary> définit la légende cliquable — l'étiquette visible — d'un widget de divulgation <details>. Cliquer sur le résumé développe ou réduit le reste du contenu de <details>, de sorte que le résumé est la partie qui reste toujours à l'écran, que le widget soit ouvert ou fermé.

L'élément <summary> doit être le premier enfant d'un élément <details>. Si <details> n'a pas de <summary>, le navigateur fournit une étiquette par défaut (généralement le mot « Details »), ce qui correspond rarement à ce que vous souhaitez — presque tous les widgets de divulgation devraient donc en inclure un.

Cette page couvre la syntaxe de <summary>, son comportement, ses caractéristiques d'accessibilité, l'événement toggle et la façon de le styliser (notamment la suppression du triangle de divulgation).

Syntaxe

La balise <summary> fonctionne par paires. Le texte de l'étiquette est écrit entre les balises ouvrante <summary> et fermante </summary>, et il se place directement à l'intérieur de <details>.

Exemple de la balise HTML `<summary>`

Balise HTML <summary>

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <details>
      <summary>Copyright 2013-2014.</summary>
      <p>W3docs. All rights reserved.</p>
      <p>The content of the website is the property of W3Docs.com.</p>
    </details>
  </body>
</html>

Essayez vous-même »

Contenu enrichi dans `<summary>`

Un résumé n'est pas limité au texte brut. Il peut contenir du contenu en ligne tel que <strong>, <em>, <code> ou une icône, ce qui est pratique pour mettre en valeur l'étiquette :

<details>
  <summary><strong>Shipping & returns</strong> — read before ordering</summary>
  <p>Orders ship within 2 business days. Returns accepted for 30 days.</p>
</details>

Gardez le résumé court et significatif : c'est l'étiquette qu'un utilisateur lit (et qu'un lecteur d'écran annonce) pour décider d'ouvrir ou non le widget.

Accessibilité

L'élément <summary> expose un rôle ARIA button implicite aux technologies d'assistance, et il est focusable et utilisable au clavier par défaut :

Tab déplace le focus sur le résumé.
Entrée ou Espace bascule l'état ouvert ou fermé du <details> parent.

Pour cette raison, vous ne devez pas envelopper un vrai <button> ou un lien à l'intérieur du résumé — le résumé est déjà le contrôle. Assurez-vous que le résumé contient une étiquette claire et descriptive afin que les utilisateurs qui naviguent par tabulation ou avec un lecteur d'écran sachent ce que révèle le widget.

L'événement `toggle` et `details.open`

L'état ouvert/fermé d'un widget de divulgation réside sur l'élément <details>, pas sur le résumé. L'attribut boolean open reflète cet état, et vous pouvez le lire ou le définir en tant que details.open en JavaScript.

Chaque fois que l'état change — par un clic, le clavier ou un script — le navigateur déclenche un événement toggle sur l'élément <details>. L'écouter vous permet de réagir à l'ouverture ou à la fermeture du widget par l'utilisateur (par exemple, pour charger du contenu de façon différée ou envoyer des données analytiques) plutôt que d'interroger l'état :

const details = document.querySelector('details');

details.addEventListener('toggle', () => {
  console.log('Details is now', details.open ? 'open' : 'closed');
});

Comment styliser la balise `<summary>`

Le style par défaut d'un <summary> utilise la propriété CSS display avec la valeur list-item, ce qui dessine le triangle de divulgation (le marqueur) à côté de l'étiquette.

Vous pouvez styliser le résumé comme n'importe quel autre élément — changer sa couleur, ajouter du rembourrage ou définir un cursor :

summary {
  color: blue;
  cursor: pointer;
  padding: 8px;
}

Suppression du triangle de divulgation

Pour masquer le triangle par défaut de manière fiable sur tous les navigateurs, supprimez le marqueur de liste et effacez également le marqueur WebKit/Blink hérité :

summary {
  list-style: none; /* Firefox and standards-based browsers */
}

summary::-webkit-details-marker {
  display: none; /* Safari and older Chrome */
}

Attributs

La balise <summary> n'a pas d'attributs propres obligatoires. Elle prend en charge les attributs globaux et les attributs d'événement.

Construire une FAQ / un accordéon

Étant donné que chaque <details> fonctionne indépendamment, vous pouvez en placer plusieurs sur une page pour créer une FAQ ou un accordéon. Chaque <summary> est la question, et le contenu masqué est la réponse :

<details>
  <summary>How do I track my order?</summary>
  <p>Use the tracking link in your confirmation email.</p>
</details>

<details>
  <summary>Can I change my shipping address?</summary>
  <p>Yes, as long as the order has not yet shipped.</p>
</details>

<details>
  <summary>Do you ship internationally?</summary>
  <p>We ship to most countries. Rates are shown at checkout.</p>
</details>

Pour n'autoriser l'ouverture que d'une seule section à la fois (un vrai accordéon), donnez aux éléments <details> le même attribut name afin que le navigateur les maintienne mutuellement exclusifs.

La balise <summary> est l'un des éléments HTML5. Voir aussi l'élément <details> qu'elle étiquette.

Pratique

Quelle affirmation concernant la balise HTML summary est correcte ?

Elle définit l'étiquette cliquable toujours visible d'un widget de divulgation details et doit en être le premier enfant.Elle n'est affichée dans le navigateur que lorsque l'élément details est fermé.Elle fournit une aide visuelle pour la navigation sur le site.Elle est utilisée pour spécifier des méta-informations dans la page web.