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

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'attributclosedby de l'élément<dialog>, qui indique les types d'actions utilisateur permettant de fermer la boîte de dialogue.

HTMLDialogElement.open

Booléen reflétant l'attribut HTMLopen, 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 devientinerte 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 deaddEventListener() 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 via la méthodeHTMLDialogElement.requestClose().

close

Déclenché lorsque la boîte de dialogue est fermée, que ce soit avec la toucheÉchap, la méthodeHTMLDialogElement.close(), ou en soumettant un formulaire à l'intérieur de la boîte de dialogue avecmethod="dialog".

Exemples

Ouvrir une boîte de dialogue modale

L'exemple suivant montre un bouton qui, lorsqu'il est cliqué, utilise la fonctionHTMLDialogElement.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 boutonAnnuler pour fermer la boîte de dialogue (via la fonctionHTMLDialogElement.close()), ou soumettre le formulaire avec le boutonConfirmer.

Cet exemple montre comment utiliser tous les événements de « changement d'état » pouvant être déclenchés sur la boîte de dialogue :cancel,close, ainsi que les événements héritésbeforetoggle ettoggle.

HTML

<!-- boîte de dialogue contextuelle, contenant un formulaire --><dialog>  <form method="dialog">    <p>      <label for="favAnimal">Animal favori&nbsp;:</label>      <select name="favAnimal">        <option></option>        <option>Crevette d'eau salée</option>        <option>Panda roux</option>        <option>Singe-araignée</option>      </select>    </p>    <div>      <button type="reset">Annuler</button>      <button type="submit">Confirmer</button>    </div>  </form></dialog><div>  <button>Mettre à jour les informations</button></div>

<pre></pre>

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

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

JavaScript

Affichage de la boîte de dialogue

Le code commence par récupérer les objets pour les éléments<button>, l'élément<dialog> et l'élément<select>.Il ajoute ensuite un écouteur d'événements pour appeler la fonctionHTMLDialogElement.showModal() lorsque le boutonMettre à jour est cliqué.

const updateButton = document.getElementById("updateDetails");const confirmButton = document.getElementById("submit");const cancelButton = document.getElementById("cancel");const dialog = document.getElementById("favDialog");const selectElement = document.getElementById("favAnimal");// Le bouton Mettre à jour ouvre la boîte de dialogue modaleupdateButton.addEventListener("click", () => {  dialog.showModal();});

Boutons Annuler et Confirmer

On ajoute ensuite des écouteurs aux événementsclick des boutonsConfirmer etAnnuler.Les gestionnaires appellentHTMLDialogElement.close() avec la valeur sélectionnée (si présente) ou sans valeur, ce qui définit la valeur de retour de la boîte de dialogue (HTMLDialogElement.returnValue) à la valeur sélectionnée ou ànull.

// Le bouton Confirmer ferme la boîte de dialogue si une valeur est sélectionnée.confirmButton.addEventListener("click", () => {  if (selectElement.value) {    // Définit dialog.returnValue à la valeur sélectionnée    dialog.close(selectElement.value);  }});// Le bouton Annuler ferme la boîte de dialoguecancelButton.addEventListener("click", () => {  dialog.close(); // Définit dialog.returnValue à null});

Appelerclose() déclenche également l'événementclose, que nous implémentons ci-dessous en journalisant la valeur de retour de la boîte de dialogue.Si le boutonConfirmer a été cliqué, cela doit être la valeur sélectionnée dans la boîte de dialogue, sinon ce seranull.

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

Événement cancel

L'événementcancel 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éthodeHTMLDialogElement.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éHTMLDialogElement.returnValue à"" pour effacer toute valeur éventuellement définie.

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

Événement toggle

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

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

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

Événement beforetoggle

L'événementbeforetoggle (hérité deHTMLElement) 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.

dialog.addEventListener("beforetoggle", (event) => {  log(    `beforetoggle event : oldState : ${event.oldState}, newState : ${event.newState}`,  );  // Appelez event.preventDefault() pour empêcher l'ouverture de la boîte de dialogue  /*    if (shouldCancel()) {        event.preventDefault();    }  */});

Résultat

Notez que les boutonsConfirmer etAnnuler déclenchent tous deux l'événementclose, et que le résultat doit refléter l'option sélectionnée dans la boîte de dialogue.

Spécifications

Compatibilité des navigateurs

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Voir aussi

• Élément HTML implémentant cette interface :
  • <dialog>