HTMLDialogElement

Proprits d'instance

Hrite galement des proprits de son interface parente, HTMLElement.

HTMLDialogElement.closedBy

Chane de caractres dfinissant ou retournant la valeur de l'attribut HTML closedby, qui indique les types d'actions utilisateur permettant de fermer la bote de dialogue.

HTMLDialogElement.open

Boolen refltant l'attribut HTML open, indiquant si la bote de dialogue est disponible pour l'interaction.

HTMLDialogElement.returnValue

Chane de caractres dfinissant ou retournant la valeur de retour de la bote de dialogue.

Mthodes d'instance

Hrite galement des mthodes de son interface parente, HTMLElement.

HTMLDialogElement.close()

Ferme la bote de dialogue. Une chane de caractres optionnelle peut tre passe en argument, ce qui met jour la proprit returnValue de la bote de dialogue.

HTMLDialogElement.requestClose()

Demande la fermeture de la bote de dialogue. Une chane de caractres optionnelle peut tre passe en argument, ce qui met jour la proprit returnValue de la bote de dialogue.

HTMLDialogElement.show()

Affiche la bote de dialogue de manire non modale, c'est--dire en permettant toujours l'interaction avec le contenu extrieur la bote de dialogue.

HTMLDialogElement.showModal()

Affiche la bote de dialogue en modal, au-dessus de toute autre bote de dialogue ventuellement prsente. Tout ce qui se trouve en dehors de la bote de dialogue est inert et les interactions extrieures sont bloques.

vnements

Hrite galement des vnements de son interface parente, HTMLElement.

coutez ces vnements l'aide de addEventListener() ou en assignant un couteur la proprit oneventname de cette interface.

cancel

Dclench lorsque la bote de dialogue reoit une demande de fermeture, que ce soit avec la touche chap ou avec la mthode requestClose(). Si l'vnement est annul (avec Event.preventDefault()), la bote de dialogue reste ouverte. Sinon, la bote de dialogue se ferme et l'vnement close est dclench.

close

Dclench lorsque la bote de dialogue est ferme.

Exemples

Ouvrir / fermer une bote de dialogue modale

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

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

L'exemple montre :

1. Fermer un formulaire avec la fonction close()
2. Fermer un formulaire lors de la soumission et dfinir la valeur de retour de la bote de dialogue returnValue
3. Fermer un formulaire avec la touche chap
4. L'vnements de  changement d'tat  pouvant tre dclenchs sur la bote de dialogue : cancel et close, ainsi que les vnements hrits beforetoggle et toggle.

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 sale</option>
        <option>Panda roux</option>
        <option>Singe-araigne</option>
      </select>
    </p>
    <div>
      <button id="submit" type="submit">Confirmer</button>
    </div>
  </form>
</dialog>

<button id="open">Ouvrir la bote de dialogue</button>

<pre id="log"></pre>

#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 bote de dialogue

Le code commence par rcuprer les objets pour l'lment <dialog>, les lments <button> et l'lment <select>. Il ajoute ensuite un couteur d'vnements pour appeler la fonction HTMLDialogElement.showModal() lorsque le bouton Ouvrir la bote de dialogue est cliqu.

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

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

Fermer la bote de dialogue lorsque le bouton Fermer est cliqu

Ensuite, nous ajoutons un couteur pour l'vnement click du bouton Fermer. Le gestionnaire dfinit la returnValue et appelle la fonction close() pour fermer la bote de dialogue.

// Le bouton ferme la bote de dialogue
const closeButton = document.getElementById("close");
closeButton.addEventListener("click", () => {
  dialog.returnValue = ""; // Rinitialise la valeur
  log(`dialog: close()`);
  dialog.close();
  // De manire alternative, nous pourrions utiliser dialog.requestClose(""); avec une valeur de retour vide.
});

Obtenir la returnValue de close

Appeler close() (ou soumettre avec succs un formulaire avec method="dialog") dclenche l'vnement close, que nous implmentons ci-dessous en journalisant la valeur de retour de la bote de dialogue.

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

vnement cancel

L'vnement cancel est dclench lorsque des  moyens spcifiques la plateforme  sont utiliss pour fermer la bote de dialogue, comme la touche chap. Il est aussi dclench lorsque la mthode requestClose() est appele. C'est un vnement  annulable , ce qui signifie qu'on peut l'utiliser pour empcher la fermeture de la bote de dialogue. Ici, on traite simplement l'annulation comme une opration de fermeture, et on rinitialise la proprit returnValue "" pour effacer toute valeur ventuellement dfinie.

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

vnement toggle

L'vnement toggle (hrit de HTMLElement) est dclench juste aprs l'ouverture ou la fermeture d'une bote de dialogue (mais avant l'vnement close).

Ici, on ajoute un couteur pour journaliser l'ouverture et la fermeture de la bote de dialogue.

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

vnement beforetoggle

L'vnement beforetoggle (hrit de HTMLElement) est un vnement annulable dclench juste avant l'ouverture ou la fermeture d'une bote de dialogue. Si besoin, il peut tre utilis pour empcher l'affichage d'une bote de dialogue, ou pour effectuer des actions sur d'autres lments affects par l'tat ouvert/ferm de la bote de dialogue, comme l'ajout de classes pour dclencher des animations.

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

dialog.addEventListener("beforetoggle", (event) => {
  log(
    `vnement beforetoggle  : ancien tat : ${event.oldState}, nouvel tat : ${event.newState}`,
  );

  // Appelez event.preventDefault() pour empcher l'ouverture de la bote de dialogue
  /*
    if (shouldCancel()) {
        event.preventDefault();
    }
  */
});

Rsultat

Essayez l'exemple ci-dessous. Notez que les boutons Confirmer et Fermer dclenchent tous deux l'vnement close, et que le rsultat doit reflter l'option slectionne dans la bote de dialogue.

Spcifications

Compatibilit des navigateurs

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

Voir aussi

• L'lment HTML <dialog>