API Popover

Un schéma très courant sur le Web consiste à afficher des contenus par-dessus d'autres, attirant l'attention de la personne sur des informations importantes ou des actions à réaliser. Ces contenus peuvent prendre plusieurs noms : superpositions, popups, popovers, boîtes de dialogue, etc. Nous les appellerons popovers dans cette documentation. En règle générale, ils peuvent être :

Modaux

Ce qui signifie que, lorsqu'un popover est affiché, le reste de la page est rendu non interactif jusqu'à ce qu'on interagisse avec le popovers d'une manière ou d'une autre (par exemple pour effectuer un choix important).

Non-modaux

Ce qui signifie que le reste de la page reste interactif pendant que le popover est affiché.

Les popovers créés à l'aide de l'API Popover sont toujours non-modaux. Si vous souhaitez créer un popover modal, l'élément <dialog> est la bonne solution. Cependant, gardez à l'esprit que les éléments <dialog> ne sont pas placés dans la couche supérieure par défaut, contrairement aux popovers. Il y a un recoupement important entre les deux : il est tout à fait possible de créer un popover persistant, et de le contrôler en utilisant du HTML déclaratif. Vous pouvez même transformer un élément <dialog> en popover si vous souhaitez combiner le contrôle des popovers et le placement en surimpression avec la sémantique des boîtes de dialogue.

Les cas d'utilisation typiques de l'API Popover incluent les éléments d'interfaces utilisateur interactifs comme les menus d'action, les notifications personnalisées de type toast, les suggestions d'éléments de formulaire, les sélecteurs de contenu ou les interfaces d'apprentissage.

Vous pouvez créer des popovers de deux manières différentes :

• De manière déclarative, via un ensemble de nouveaux attributs HTML. Un popover simple avec un bouton d'activation peut être créé en utilisant le code suivant :

  html

  <button popovertarget="mypopover">Basculer le popover</button>
  <div id="mypopover" popover>Contenu du popover</div>
  

• Via une API JavaScript. Par exemple, la méthode HTMLElement.togglePopover() peut être utilisée pour basculer un popover entre les états affiché et masqué.

Il existe également de nouveaux évènements pour réagir à l'activation d'un popover, ainsi que des fonctionnalités CSS pour faciliter la mise en forme des popovers. Toutes les fonctionnalités associées sont répertoriées ci-après.

Voir Utiliser l'API Popover pour un guide détaillé sur l'utilisation de cette API.

popover

Un attribut universel qui transforme un élément en élément popover et qui prend un état de popover ("auto" ou "manual") comme valeur.

popovertarget

Transforme un élément <button> ou <input> en bouton de contrôle de popover. La valeur de cet attribut correspond à l'identifiant de l'élément popover à contrôler.

popovertargetaction

Spécifie l'action à effectuer ("hide", "show" ou "toggle") sur l'élément popover contrôlé par un élément de contrôle <button> ou <input>.

::backdrop

Le pseudo-élément ::backdrop est un élément plein écran placé directement derrière les éléments popovers, permettant d'ajouter des effets au contenu de la page derrière les popovers si nécessaire (par exemple en le floutant).

:popover-open

La pseudo-classe :popover-open correspond à un élément popover uniquement lorsqu'il est affiché. Elle peut être utilisée pour styliser les éléments popovers lorsqu'ils sont affichés.

ToggleEvent

Représente un évènement de notification lorsqu'un élément popover bascule entre les états affiché et masqué. Elle est implémentée par les évènements beforetoggle et toggle, qui se déclenchent sur les popovers lorsque leur état change.

HTMLElement.popover

Permet de connaître ou de modifier l'état de l'élément popover via JavaScript ("auto" ou "manual"). Elle peut être utilisée pour détecter la prise en charge des fonctionnalités popover. Cette propriété reflète l'attribut HTML popover.

HTMLButtonElement.popoverTargetElement et HTMLInputElement.popoverTargetElement

Permet de connaître ou de modifier l'élément popover contrôlé par le bouton. C'est l'équivalent JavaScript de l'attribut HTML popovertarget.

HTMLButtonElement.popoverTargetAction et HTMLInputElement.popoverTargetAction

Permet de connaître ou de modifier l'action à effectuer ("hide", "show" ou "toggle") sur l'élément popover contrôlé par le bouton. Cette propriété reflète la valeur de l'attribut HTML popovertargetaction.

HTMLElement.hidePopover()

Masque l'élément popover en le supprimant de la couche supérieure et en le masquant avec display: none.

HTMLElement.showPopover()

Affiche l'élément popover en le plaçant dans la couche supérieure.

HTMLElement.togglePopover()

Bascule l'élément popover entre les états affiché et masqué.

Évènement beforetoggle, rattaché à HTMLElement

Déclenché juste avant que l'état d'un élément popover ne change entre affiché et masqué, ou vice versa.

Évènement toggle, rattaché à HTMLElement

Déclenché lorsque l'état d'un élément popover a changé entre les états affiché et masqué, ou vice versa. Voir l'évènement analogue toggle de HTMLDetailsElement qui signale les changements d'états des éléments <details>.

Voir notre page d'exemples de l'API Popover pour accéder à l'ensemble des exemples MDN sur ce sujet.