API Popover

Concepts et utilisation

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, fenêtre contextuelle, boîtes de dialogue, etc. Nous les appellerons fenêtres contextuelles dans cette documentation. En règle générale, ils peuvent être :

• modales, ce qui signifie que, lorsqu'une fenêtre contextuelle est affichée, le reste de la page est rendu non interactif jusqu'à ce qu'on interagisse avec la fenêtre contextuelle d'une manière ou d'une autre (par exemple pour effectuer un choix important).
• non modales, ce qui signifie que le reste de la page reste interactif pendant que la fenêtre contextuelle est affichée.

Les fenêtres contextuelles créées à l'aide de l'API Popover sont toujours non-modales. Si vous souhaitez créer une fenêtre contextuelle modale, 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 fenêtres contextuelles. Il y a un recoupement important entre les deux : il est tout à fait possible de créer une fenêtre contextuelle persistante, et de la contrôler en utilisant du HTML déclaratif. Vous pouvez même transformer un élément <dialog> en fenêtre contextuelle si vous souhaitez combiner le contrôle des fenêtres contextuelles 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. Une fenêtre contextuelle simple avec un bouton d'activation peut être créée 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 une fenêtre contextuelle entre les états affiché et masqué.

Il existe également de nouveaux évènements pour réagir à l'activation d'une fenêtre contextuelle, ainsi que des fonctionnalités CSS pour faciliter la mise en forme des fenêtres contextuelles. 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.

Attributs HTML

interestfor Expérimental

Définit un élément HTML <a>, <button> ou <area>, ou un élément SVG <a> (voir élément <a>), comme invocateur d'intérêt. Sa valeur est l'id de l'élément cible, qui sera affecté d'une manière ou d'une autre (généralement affiché ou masqué) lorsque l'intérêt est montré ou perdu sur l'élément invocateur.

popover

Un attribut universel qui transforme un élément en une fenêtre contextuelle (popover en anglais) et qui prend un état de fenêtre contextuelle ("auto", "hint" ou "manual") comme valeur.

popovertarget

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

popovertargetaction

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

Fonctionnalités CSS

::backdrop

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

interest-delay, interest-delay-start et interest-delay-end Expérimental

La propriété raccourcie interest-delay et ses formes longues associées interest-delay-start et interest-delay-end permettent d'ajouter un délai entre le moment où la personne montre ou perd son intérêt et le moment où le navigateur agit sur ce changement.

:interest-source et :interest-target

Ces sélecteurs servent à appliquer des styles respectivement à l'invocateur d'intérêt et à l'élément cible qui lui est associé, uniquement lorsque l'intérêt est indiqué.

:popover-open

La pseudo-classe :popover-open correspond à une fenêtre contextuelle uniquement lorsqu'elle est affichée. Elle peut être utilisée pour styliser les fenêtres contextuelles lorsqu'elles sont affichées.

Interfaces

InterestEvent Expérimental

L'objet événement pour les événements interest et loseinterest. Il inclut une propriété source contenant une référence vers l'élément invocateur d'intérêt associé.

ToggleEvent

Représente un évènement de notification lorsqu'une fenêtre contextuelle 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 fenêtres contextuelles lorsque leur état change.

Extensions aux autres interfaces

Propriétés d'instance

interestForElement Expérimental

Obtient ou définit une référence vers l'élément ciblé par un invocateur d'intérêt. Si un invocateur d'intérêt HTML ou SVG référence un élément cible via son attribut interestfor, cet élément sera référencé dans la propriété interestForElement de l'objet DOM équivalent. Disponible sur les interfaces HTMLButtonElement, HTMLAnchorElement, HTMLAreaElement et SVGAElement.

HTMLElement.popover

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

HTMLButtonElement.popoverTargetElement et HTMLInputElement.popoverTargetElement

Permet de connaître ou de modifier la fenêtre contextuelle contrôlée 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 la fenêtre contextuelle contrôlée par le bouton. Cette propriété reflète la valeur de l'attribut HTML popovertargetaction.

Méthodes d'instance

HTMLElement.hidePopover()

Masque la fenêtre contextuelle (popover en anglais) en le supprimant de la couche supérieure et en le masquant avec display: none.

HTMLElement.showPopover()

Affiche la fenêtre contextuelle en la plaçant dans la couche supérieure.

HTMLElement.togglePopover()

Change l'état de la fenêtre contextuelle entre les états affiché et masqué.

Évènements

Évènement beforetoggle

Déclenché juste avant que l'état d'une fenêtre contextuelle (popover en anglais) ne change entre affiché et masqué, ou vice versa.

Évènement toggle

Déclenché juste après que l'état d'une fenêtre contextuelle a changé entre affiché et masqué, ou inversement.

interest Expérimental

Déclenché sur l'élément cible d'un invocateur d'intérêt lorsque l'intérêt est montré, permettant d'exécuter du code en réponse.

loseinterest Expérimental

Déclenché sur l'élément cible d'un invocateur d'intérêt lorsque l'intérêt est perdu, permettant d'exécuter du code en réponse.

Exemples

• Voir notre collection de Exemples de l'API Popover ^(angl.).
• Voir notre collection d'exemples d'invocateurs d'intérêt ^(angl.).

Spécifications

Compatibilité des navigateurs

api.HTMLElement.popover

api.HTMLElement.beforetoggle_event.popover_elements

api.HTMLElement.toggle_event.popover_elements

Voir aussi

• L'attribut global HTML popover
• L'attribut HTML popovertarget
• L'attribut HTML popovertargetaction
• Le pseudo-élément CSS ::backdrop
• La pseudo-classe CSS :popover-open