HTMLButtonElement : propriété popoverTargetElement

Baseline 2024 *

Newly available

Depuis April 2024, cette fonctionnalité fonctionne sur les appareils et les versions de navigateur les plus récents. Elle peut ne pas fonctionner sur les appareils ou navigateurs plus anciens.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

La propriétépopoverTargetElement de l'interfaceHTMLButtonElement permet d'obtenir et de définir l'élément de fenêtre contextuelle (popover en anglais) à contrôler via un bouton.

Il s'agit de l'équivalent JavaScript de l'attribut HTMLpopovertarget.

Établir une relation entre une fenêtre contextuelle et son bouton d'invocation à l'aide de la propriétépopoverTargetElement a deux effets supplémentaires utiles :

Le navigateur crée une relation implicitearia-details etaria-expanded entre la fenêtre contextuelle et l'invocateur, et place la fenêtre contextuelle à une position logique dans l'ordre de navigation au clavier lorsqu'elle est affichée. Cela rend la fenêtre contextuelle plus accessible aux utilisateur·ices de clavier et de technologies d'assistance (voir aussiFonctionnalités d'accessibilité des fenêtres contextuelles).
Le navigateur crée une ancre implicite entre les deux, ce qui facilite grandement le positionnement des fenêtres contextuelles par rapport à leurs contrôles à l'aide dupositionnement d'ancre CSS. VoirPositionnement d'ancre de fenêtre contextuelle pour plus de détails.

Valeur

Une référence vers un élément de fenêtre contextuelle dans le DOM.

Cet exemple montre l'utilisation basique de l'API des fenêtres contextuelles (popover en anglais) avec la valeur"toggle" définie pour la propriétépopoverTargetAction.L'attributpopover est défini sur"auto", donc la fenêtre contextuelle peut être fermée (« light-dismissed ») en cliquant en dehors de la zone de la fenêtre contextuelle.

On définit d'abord un élément HTML<button> qui servira à afficher et masquer la fenêtre contextuelle, et un<div> qui sera la fenêtre contextuelle.Dans ce cas, on ne définit pas l'attribut HTMLpopovertargetaction sur le<button> ni l'attributpopover sur le<div>, car cela sera fait par programmation.

html

<button>Afficher/masquer la fenêtre</button><div>Ceci est le contenu&nbsp;!</div>

Le code JavaScript commence par récupérer une référence vers les éléments<div> et<button>.Il définit ensuite une fonction pour vérifier la prise en charge de l'API des fenêtres contextuelles.

const popover = document.getElementById("monpopover");const toggleBtn = document.getElementById("toggleBtn");// Vérifie la prise en charge de l'API Popover.function supportsPopover() {  return HTMLElement.prototype.hasOwnProperty("popover");}

Si l'API des fenêtres contextuelles est prise en charge, le code définit l'attributpopover de l'élément<div> à"auto" et fait de ce<div> la cible du bouton de bascule.On définit ensuite la propriétépopoverTargetAction du<button> à"toggle".Si l'API des fenêtres contextuelles n'est pas prise en charge, on modifie le texte du<div> pour l'indiquer et on masque le bouton de bascule.

if (supportsPopover()) {  // Définit l'élément <div> comme étant une fenêtre contextuelle automatique  popover.popover = "auto";  // Définit le bouton comme étant le contrôle de la fenêtre contextuelle  toggleBtn.popoverTargetElement = popover;  // Définit que le bouton peut afficher/masquer la fenêtre contextuelle  toggleBtn.popoverTargetAction = "toggle";} else {  popover.textContent = "L'API Popover n'est pas prise en charge.";  toggleBtn.hidden = true;}

Note :Un élément fenêtre contextuelle (popover en anglais) est masqué par défaut, mais si l'API n'est pas prise en charge, votre élément s'affichera « comme d'habitude ».

Vous pouvez essayer l'exemple ci-dessous.Affichez et masquez la fenêtre contextuelle en cliquant sur le bouton.La fenêtre contextuelle"auto" peut aussi être « light-dismissed » en cliquant en dehors du texte de la fenêtre contextuelle.