HTMLDialogElement - Les API Web | MDN

Basculer la barre latérale

Thème

Automatique
Clair
Sombre

Français

Se souvenir de la langue En savoir plus

HTMLDialogElement

Baseline Large disponibilité *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis mars 2022.

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

L'interface HTMLDialogElement fournit des méthodes pour manipuler les éléments <dialog>. Elle hérite des propriétés et méthodes de l'interface parente HTMLElement.

EventTarget Node Element HTMLElement HTMLDialogElement

Dans cet article

Propriétés d'instance

Hérite également des propriétés de son interface parente, HTMLElement.

HTMLDialogElement.closedBy

Chaîne de caractères définissant ou retournant la valeur de l'attribut HTML closedby, qui indique les types d'actions utilisateur permettant de fermer la boîte de dialogue.

HTMLDialogElement.open

Booléen reflétant l'attribut HTML open, indiquant si la boîte de dialogue est disponible pour l'interaction.

HTMLDialogElement.returnValue

Chaîne de caractères définissant ou retournant la valeur de retour de la boîte de dialogue.

Méthodes d'instance

Hérite également des méthodes de son interface parente, HTMLElement.

HTMLDialogElement.close()

Ferme la boîte de dialogue. Une chaîne de caractères optionnelle peut être passée en argument, ce qui met à jour la propriété returnValue de la boîte de dialogue.

HTMLDialogElement.requestClose()

Demande la fermeture de la boîte de dialogue. Une chaîne de caractères optionnelle peut être passée en argument, ce qui met à jour la propriété returnValue de la boîte de dialogue.

HTMLDialogElement.show()

Affiche la boîte de dialogue de manière non modale, c'est-à-dire en permettant toujours l'interaction avec le contenu extérieur à la boîte de dialogue.

HTMLDialogElement.showModal()

Affiche la boîte de dialogue en modal, au-dessus de toute autre boîte de dialogue éventuellement présente. Tout ce qui se trouve en dehors de la boîte de dialogue est inert et les interactions extérieures sont bloquées.

Évènements

Hérite également des évènements de son interface parente, HTMLElement.

Écoutez ces évènements à l'aide de addEventListener() ou en assignant un écouteur à la propriété oneventname de cette interface.

cancel

Déclenché lorsque la boîte de dialogue reçoit une demande de fermeture, que ce soit avec la touche Échap ou avec la méthode requestClose(). Si l'évènement est annulé (avec Event.preventDefault()), la boîte de dialogue reste ouverte. Sinon, la boîte de dialogue se ferme et l'évènement close est déclenché.

Déclenché lorsque la boîte de dialogue est fermée.

Exemples

Ouvrir / fermer une boîte de dialogue modale

L'exemple suivant montre un bouton qui, lorsqu'il est cliqué, utilise la fonction showModal() pour ouvrir une boîte de dialogue modale <dialog> contenant un formulaire.

Lorsque la boîte de dialogue est ouverte, tout ce qui n'est pas son contenu devient inerte. Vous pouvez cliquer sur le bouton Fermer pour fermer la boîte de dialogue (avec la fonction close()), ou soumettre le formulaire avec le bouton Confirmer.

L'exemple montre :

Fermer un formulaire avec la fonction close()
Fermer un formulaire lors de la soumission et définir la valeur de retour de la boîte de dialogue returnValue
Fermer un formulaire avec la touche Échap
L'évènements de « changement d'état » pouvant être déclenchés sur la boîte de dialogue : cancel et close, ainsi que les évènements hérités beforetoggle et toggle.

HTML

html
<dialog id="dialog">
  <button id="close" type="button">Fermer</button>
  <form method="dialog" id="form">
    <p>
      <label for="fav-animal">Animal favori&nbsp;:</label>
      <select id="fav-animal" name="favAnimal" required>
        <option></option>
        <option>Crevette d'eau salée</option>
        <option>Panda roux</option>
        <option>Singe-araignée</option>
      </select>
    </p>
    <div>
      <button id="submit" type="submit">Confirmer</button>
    </div>
  </form>
</dialog>

<button id="open">Ouvrir la boîte de dialogue</button>

#log {
  height: 170px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.getElementById("log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Ouvrir la boîte de dialogue

Le code commence par récupérer les objets pour l'élément <dialog>, les éléments <button> et l'élément <select>. Il ajoute ensuite un écouteur d'évènements pour appeler la fonction HTMLDialogElement.showModal() lorsque le bouton Ouvrir la boîte de dialogue est cliqué.

js
const dialog = document.getElementById("dialog");
const openButton = document.getElementById("open");

// Le bouton Mettre à jour ouvre la boîte de dialogue modale
openButton.addEventListener("click", () => {
  log(`dialog: showModal()`);
  dialog.showModal();
});

Fermer la boîte de dialogue lorsque le bouton Fermer est cliqué

Ensuite, nous ajoutons un écouteur pour l'évènement click du bouton Fermer. Le gestionnaire définit la returnValue et appelle la fonction close() pour fermer la boîte de dialogue.

js
// Le bouton ferme la boîte de dialogue
const closeButton = document.getElementById("close");
closeButton.addEventListener("click", () => {
  dialog.returnValue = ""; // Réinitialise la valeur
  log(`dialog: close()`);
  dialog.close();
  // De manière alternative, nous pourrions utiliser dialog.requestClose(""); avec une valeur de retour vide.
});

Obtenir la returnValue de close

Appeler close() (ou soumettre avec succès un formulaire avec method="dialog") déclenche l'évènement close, que nous implémentons ci-dessous en journalisant la valeur de retour de la boîte de dialogue.

js
dialog.addEventListener("close", (event) => {
  log(`close_event : (dialog.returnValue : "${dialog.returnValue}")`);
});

Évènement cancel

L'évènement cancel est déclenché lorsque des « moyens spécifiques à la plateforme » sont utilisés pour fermer la boîte de dialogue, comme la touche Échap. Il est aussi déclenché lorsque la méthode requestClose() est appelée. C'est un évènement « annulable », ce qui signifie qu'on peut l'utiliser pour empêcher la fermeture de la boîte de dialogue. Ici, on traite simplement l'annulation comme une opération de fermeture, et on réinitialise la propriété returnValue à "" pour effacer toute valeur éventuellement définie.

js
dialog.addEventListener("cancel", (event) => {
  log(`cancel_event : (dialog.returnValue : "${dialog.returnValue}")`);
  dialog.returnValue = ""; // Réinitialise la valeur
});

Évènement toggle

L'évènement toggle (hérité de HTMLElement) est déclenché juste après l'ouverture ou la fermeture d'une boîte de dialogue (mais avant l'évènement close).

Ici, on ajoute un écouteur pour journaliser l'ouverture et la fermeture de la boîte de dialogue.

Note : Les évènements toggle et beforetoggle peuvent ne pas être déclenchés sur les éléments dialog dans tous les navigateurs. Sur ces versions, vous pouvez vérifier la propriété open après avoir tenté d'ouvrir/fermer la boîte de dialogue.

js
dialog.addEventListener("toggle", (event) => {
  log(`toggle_event : nouvel état : ${event.newState}`);
});

Évènement beforetoggle

L'évènement beforetoggle (hérité de HTMLElement) est un évènement annulable déclenché juste avant l'ouverture ou la fermeture d'une boîte de dialogue. Si besoin, il peut être utilisé pour empêcher l'affichage d'une boîte de dialogue, ou pour effectuer des actions sur d'autres éléments affectés par l'état ouvert/fermé de la boîte de dialogue, comme l'ajout de classes pour déclencher des animations.

Dans ce cas, on journalise simplement l'ancien et le nouvel état.

js
dialog.addEventListener("beforetoggle", (event) => {
  log(
    `évènement beforetoggle  : ancien état : ${event.oldState}, nouvel état : ${event.newState}`,
  );

  // Appelez event.preventDefault() pour empêcher l'ouverture de la boîte de dialogue
  /*
    if (shouldCancel()) {
        event.preventDefault();
    }
  */
});

Résultat

Essayez l'exemple ci-dessous. Notez que les boutons Confirmer et Fermer déclenchent tous deux l'évènement close, et que le résultat doit refléter l'option sélectionnée dans la boîte de dialogue.