Détails et résumé

Découvrez comment fonctionnent les éléments de résumé et les détails très utiles, et où les utiliser.

Il s'agit d'une commande d'interface utilisateur qui permet de masquer et d'afficher du contenu. Si vous lisez ce document sur web.dev et que votre fenêtre d'affichage fait moins de 106 ems, cliquez sur "Sur cette page" au-dessus de ce paragraphe pour afficher la table des matières de cette section. Si vous ne la voyez pas, réduisez la taille du navigateur pour afficher la navigation dans la table des matières sur cette page en tant que widget de divulgation.

L'interface utilisateur graphique accordion est une série de widgets de divulgation empilés verticalement. La page des questions fréquentes sur de nombreux sites constitue un cas d'utilisation courant de l'interface utilisateur accordéon. Une FAQ en accordéon contient une liste de questions visibles. Un clic sur une question permet de développer ou de "diversifier" la réponse à cette question.

jQuery inclut un modèle d'interface utilisateur en accordéon depuis au moins 2009. La solution d'accordéon initiale sans JavaScript consistait à définir chaque question des questions fréquentes comme une <label>, suivie d'une coche associée à l'étiquette, puis à afficher la réponse <div> lorsque la coche était cochée. Le CSS ressemblait à ceci:

#FAQ [type="checkbox"] + div.answer {
  /* all the answer styles */
  display: none;
}
#FAQ [type="checkbox"]:checked + div.answer {
  display: block;
}

Pourquoi cette histoire ? Les widgets de divulgation tels que les accordéons (sans JavaScript ni contrôle de formulaire) sont un ajout relativement récent. Les éléments <details> et <summary> ne sont entièrement compatibles avec tous les navigateurs récents que depuis janvier 2020. Vous pouvez désormais créer des widgets de communiqué fonctionnels, quoique moins attrayants, qu'en utilisant uniquement du code HTML sémantique. Les éléments <details> et <summary> sont tout ce dont vous avez besoin: il s'agit d'un moyen intégré de gérer l'expansion et le repli du contenu. Lorsqu'un utilisateur clique ou appuie sur une <summary>, ou libère la touche Entrée lorsque <summary> est sélectionné, le contenu du <details> parent devient visible.

Comme pour tout contenu sémantique, vous pouvez améliorer progressivement les fonctionnalités et l'apparence par défaut. Dans le cas présent, nous n'avons ajouté qu'une petite partie de CSS:

Notez que ces Codepens ne contiennent pas de code JavaScript.

Modification de la visibilité: attribut open

L'élément <details> est le conteneur du widget d'information. <summary> est le résumé ou la légende de son parent <details>. Le résumé est toujours affiché et fonctionne comme un bouton qui active ou désactive l'affichage du reste du contenu du parent. L'interaction avec <summary> active ou désactive l'affichage des frères et sœurs résumé auto-étiquetés en activant/désactivant l'attribut open de l'élément <details>.

L'attribut open est un attribut booléen. S'il est présent, peu importe sa valeur ou son absence, tous les contenus de <details> sont présentés à l'utilisateur. Si l'attribut open n'est pas présent, seul le contenu de <summary> est affiché.

Étant donné que l'attribut open est ajouté et supprimé automatiquement lorsque l'utilisateur interagit avec la commande, il peut être utilisé en CSS pour appliquer un style différent à l'élément en fonction de son état.

Vous pouvez créer un accordéon avec une liste de plusieurs éléments <details>, chacun avec un enfant <summary>. Si vous omettez l'attribut open dans votre code HTML, les <details> seront tous réduits ou fermés, et seuls les en-têtes de résumé seront visibles au chargement de la page. Chaque titre ouvre le champ du reste du contenu dans l'élément <details> parent. Si vous incluez l'attribut open dans votre code HTML, <details> s'affiche en grand format avec le contenu visible au chargement de la page.

Le contenu masqué à l'état réduit peut faire l'objet de recherches dans certains navigateurs, mais pas dans d'autres, même si le contenu réduit ne fait pas partie du DOM. Si vous effectuez une recherche dans Edge ou Chrome, les détails contenant un terme de recherche sont développés pour afficher l'occurrence. Ce comportement n'est pas reproduit dans Firefox ou Safari.

<summary> doit être le premier enfant d'un élément <details> et doit représenter un résumé, une légende ou une légende pour le reste du contenu de l'élément <details> parent dans lequel il est imbriqué. Le contenu de l'élément <summary> peut être n'importe quel titre, texte brut ou code HTML pouvant être utilisé dans un paragraphe.

Activer/Désactiver le repère de résumé

Dans les deux précédents codepens, vous noterez la flèche du côté inline-start du résumé. Un widget d'affichage est généralement présenté à l'écran sous la forme d'un petit triangle qui pivote (ou se tourne) pour indiquer qu'il est ouvert ou fermé. Un libellé s'affiche à côté du triangle. Le contenu de l'élément <summary> définit le widget d'information. La flèche qui pivote en haut de chaque section est un ::marker défini sur l'élément <summary>. Comme les éléments de liste, l'élément <summary> accepte la propriété abrégée list-style et ses propriétés de longue durée, y compris list-style-type. Vous pouvez styliser le triangle d'affichage avec CSS, en remplaçant le repère d'un triangle par tout autre type de puce, y compris une image avec list-style-image.

Pour appliquer d'autres styles, utilisez un sélecteur semblable à details summary::marker. Le pseudo-élément ::marker n'accepte qu'un nombre limité de styles. Il est courant de supprimer ::marker et de le remplacer par ::before, plus facile à styliser, car les styles CSS modifient légèrement le style du contenu généré en fonction de la présence (ou de l'absence) de l'attribut ouvert. Vous pouvez supprimer l'icône du widget d'information en définissant list-style: none ou le contenu du repère sur none, mais incluez toujours des indicateurs visuels pour informer les utilisateurs voyants que le contenu du résumé est un bouton d'activation qui affiche et masque le contenu lors de l'activation.

details summary::before {
  /* all the styles */
}
details[open] summary::before {
  /* changes applied when open only */
}

Cet exemple supprime le repère par défaut et ajoute du contenu généré pour créer un + lorsque les détails sont fermés et un - lorsqu'ils sont ouverts.

Si vous souhaitez que le bloc des détails s'affiche par défaut, incluez l'attribut open dans la balise d'ouverture <details>. Vous pouvez également ajouter un espace entre chaque boîte de dialogue et modifier la rotation du repère créé avec le contenu généré pour améliorer l'apparence:

Comment les erreurs sont-elles traitées ?

Si vous n'incluez pas de <summary>, le navigateur en crée un pour vous: avec un repère et le mot "details". Ce résumé fait partie d'une racine fantôme. Par conséquent, aucun style de résumé CSS de l'auteur n'est appliqué. Malheureusement, Safari n'inclut pas ces détails dans l'ordre de sélection du clavier.

Si vous incluez un <summary>, mais qu'il ne s'agit pas du premier élément du <details>, le navigateur affiche toujours le résumé comme il se doit. Elle fonctionne également si vous incluez un lien, un libellé ou tout autre élément interactif dans le résumé, mais que les navigateurs gèrent le contenu interactif différemment. Par exemple, si vous incluez un lien dans un récapitulatif, certains navigateurs ajoutent le résumé et le lien à l'ordre de tabulation par défaut, mais d'autres ne sélectionnent pas le lien par défaut. Si vous cliquez sur un élément <label> imbriqué dans un élément <summary>, certains navigateurs placent le curseur dans la commande de formulaire associée, tandis que d'autres le sélectionnent et activent ou désactivent l'élément <details>.

Interface HTMLDetailsElement

Comme tous les éléments HTML, le HTMLDetailsElement hérite de l'ensemble des propriétés, méthodes et événements de HTMLElement, et ajoute la propriété d'instance open et un événement toggle. La propriété HTMLDetailsElement.open est une valeur booléenne reflétant l'attribut HTML open, qui indique si le contenu de l'élément (sans compter le <summary>) doit être présenté à l'utilisateur. L'événement d'activation/désactivation est déclenché lorsque l'élément <details> est ouvert ou fermé. Vous pouvez écouter cet événement avec addEventListener().

Si vous souhaitez écrire un script pour fermer les informations ouvertes lorsque l'utilisateur ouvre d'autres détails, supprimez l'attribut ouvert à l'aide de removeAttribute("open"):

C'est le seul exemple qui utilise JavaScript. Vous n'avez probablement pas besoin de JavaScript, à l'exception de cette fonctionnalité qui permet de fermer les autres widgets de communiqué ouverts.

N'oubliez pas que <details> et <summary> peuvent être très stylisés et même être utilisés pour créer des info-bulles. Toutefois, si vous prévoyez d'utiliser ces éléments sémantiques dans des cas d'utilisation dans lesquels la sémantique native ne correspond pas, assurez-vous toujours de préserver l'accessibilité. La plupart des éléments HTML sont accessibles par défaut. Notre travail en tant que développeurs est de veiller à ce que nos contenus restent accessibles.

Testez vos connaissances

Testez vos connaissances sur les détails et le résumé.