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(), sauf qu'aucune exception n'est levée si la fenêtre contextuelle (popover en anglais) est déjà dans l'état cible.

• Si la valeur est true, la fenêtre contextuelle est affichée si elle était initialement masquée. Si elle était déjà affichée, rien ne se passe.
• Si la valeur est false, la fenêtre contextuelle est masquée si elle était initialement affichée. Si elle était 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 via 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 via le positionnement d'ancre CSS. Voir Positionnement d'ancre pour les fenêtres contextuelles pour plus de détails.

Valeur de retour

true si le popup est ouvert 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 le focus).

Le HTML de l'exemple est affiché ci-après. Le premier élément fournit les instructions sur la façon d'invoquer le popup, 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 le popup. 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="mypopover" 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 ligne.

const instructions = document.getElementById("instructions");
const popover = document.getElementById("mypopover");

if (!HTMLElement.prototype.hasOwnProperty("popover")) {
  popover.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 = popover.togglePopover();

      // Vérifie si le popover est ouvert ou fermé
      // 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