HTMLDialogElement

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 closedby 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 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 devient inerte 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 via la méthode HTMLDialogElement.requestClose().

close

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

Exemples

Ouvrir une boîte de dialogue modale

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

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és beforetoggle et toggle.

HTML

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

<div>
  <button id="updateDetails">Mettre à jour les informations</button>
</div>

<pre id="log"></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 fonction HTMLDialogElement.showModal() lorsque le bouton Mettre à 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 modale
updateButton.addEventListener("click", () => {
  dialog.showModal();
});

Boutons Annuler et Confirmer

On ajoute ensuite des écouteurs aux événements click des boutons Confirmer et Annuler. Les gestionnaires appellent HTMLDialogElement.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 dialogue
cancelButton.addEventListener("click", () => {
  dialog.close(); // Définit dialog.returnValue à null
});

Appeler close() déclenche également l'événement close, que nous implémentons ci-dessous en journalisant la valeur de retour de la boîte de dialogue. Si le bouton Confirmer a été cliqué, cela doit être la valeur sélectionnée dans la boîte de dialogue, sinon ce sera null.

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 HTMLDialogElement.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é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 closed).

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é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.

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 boutons Confirmer et Annuler 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.

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>