HTMLElement : méthode togglePopover()

Syntaxe

togglePopover()
togglePopover(force)
togglePopover(options)

Paramètres

Un booléen (force) ou un objet d'options :

force Facultatif

Un booléen, qui fait que togglePopover() se comporte comme showPopover() ou hidePopover().

• Si la valeur est true, la fenêtre contextuelle est affichée si elle est initialement masquée. Si elle est déjà affichée, rien ne se passe.
• Si la valeur est false, la fenêtre contextuelle est masquée si elle est initialement affichée. Si elle est déjà masquée, rien ne se passe.

options Facultatif

Un objet qui peut contenir les propriétés suivantes :

force Facultatif

Un booléen ; voir la description de force ci-dessus.

source Facultatif

Une référence HTMLElement ; définit par programmation l'élément déclencheur de la fenêtre contextuelle (popover en anglais) associée à l'action d'alternance, c'est-à-dire son élément de contrôle. Établir une relation entre une fenêtre contextuelle et son déclencheur avec l'option source a deux effets utiles :

• Le navigateur place la fenêtre contextuelle dans une position logique dans l'ordre de navigation au clavier lors de l'affichage. Cela rend la fenêtre contextuelle plus accessible aux utilisateur·ice·s du clavier (voir aussi Fonctionnalités d'accessibilité des fenêtres contextuelles).
• Le navigateur crée une ancre implicite entre les deux, ce qui facilite le positionnement des fenêtres contextuelles par rapport à leurs contrôles avec le positionnement d'ancre CSS. Voir Positionnement d'ancre pour les fenêtres contextuelles pour plus de détails.

Exceptions

InvalidStateError DOMException

Levée si cette méthode est appelée alors qu'un autre fenêtre contextuelle est déjà en train d'être affichée ou masquée (par exemple, au sein d'un écouteur d'évènement beforetoggle).

Valeur de retour

true si la fenêtre intrusive (popup en anglais) est ouverte après l'appel, et false sinon.

Aucune (undefined) peut être retournée dans d'anciennes versions de navigateurs (voir la compatibilité des navigateurs).

Exemples

Voir la page d'exemples de l'API Popover ^(angl.) pour accéder à la collection complète des exemples de MDN relatifs aux fenêtres contextuelles.

Affichage automatique simple

L'exemple qui suit est une version légèrement modifiée de l'exemple d'interface d'aide ^(angl.). L'exemple affiche/masque une fenêtre contextuelle (popovers en anglais) en appuyant sur une touche particulière du clavier (lorsque la fenêtre de l'exemple a la sélection).

Le HTML de l'exemple est affiché ci-après. Le premier élément fournit les instructions sur la façon d'invoquer la fenêtre intrusive, ce dont nous avons besoin, car les popups sont masqués par défaut.

<p id="instructions">
  Appuyez sur <kbd>h</kbd> pour afficher/masquer une fenêtre d'aide
  (sélectionnez d'abord la fenêtre de l'exemple).
</p>

Nous définissons ensuite un élément <div> qui est la fenêtre intrusive. Le contenu réel n'a pas d'importance, mais notez que nous avons besoin de l'attribut popover pour faire du <div> une fenêtre contextuelle afin qu'il soit masqué par défaut (nous pourrions également définir cet élément dans le JavaScript).

<div id="ma-fenetre" popover>
  <h2>Aides&nbsp;!</h2>

  <p>Vous pouvez utiliser les touches suivantes pour contrôlez l'application</p>

  <ul>
    <li>Pressez la touche <ins>C</ins> pour commander du fromage</li>
    <li>Pressez la touche <ins>T</ins> pour commander du tofu</li>
    <li>Pressez la touche <ins>B</ins> pour commander du bacon</li>
  </ul>
</div>

Le JavaScript de l'exemple est présenté ci-dessous. Nous vérifions d'abord si les fenêtres contextuelles sont prises en charge, et si ce n'est pas le cas, nous masquons la div fenêtre contextuelle afin qu'elle ne soit pas affichée en incise.

const instructions = document.getElementById("instructions");
const fenetreContextuelle = document.getElementById("ma-fenetre");

if (!HTMLElement.prototype.hasOwnProperty("popover")) {
  fenetreContextuelle.innerText = "";
  instructions.innerText =
    "Votre navigateur ne prend pas en charge les fenêtres contextuelles.";
}

Si les fenêtres contextuelles sont prises en charge, nous ajoutons un écouteur pour la touche h et utilisons cela pour ouvrir la fenêtre contextuelle. Nous affichons également si la fenêtre contextuelle était ouverte ou fermée après l'appel, mais uniquement si une valeur true ou false a été retournée.

if (Object.hasOwn(HTMLElement.prototype, "popover")) {
  document.addEventListener("keydown", (event) => {
    if (event.key === "h") {
      const popupOpened = fenetreContextuelle.togglePopover();

      // Vérifie si la fenêtre contextuelle est ouverte ou fermée
      // sur les navigateurs qui le prennent en charge
      if (popupOpened !== undefined) {
        instructions.innerText += popupOpened === true ? `\nOuvert` : `\nFermé`;
      }
    }
  });
}

Vous pouvez tester cela en utilisant l'exemple interactif ci-dessous.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'attribut HTML universel popover
• L'API Popover