HTMLDialogElement : méthode requestClose()

Baseline 2025

Nouvellement disponible

Depuis May 2025, cette fonctionnalité fonctionne sur les appareils et les versions de navigateur les plus récents. Elle peut ne pas fonctionner sur les appareils ou navigateurs plus anciens.

En savoir plus
Voir la compatibilité complète

La méthode requestClose() de l'interface HTMLDialogElement demande la fermeture de l'élément HTML <dialog>. 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.

Cette méthode diffère de close(), car elle déclenche d'abord un évènement cancel, puis l'évènement close. Les auteur·ice·s peuvent appeler Event.preventDefault() dans le gestionnaire de l'évènement cancel pour empêcher la fermeture de la boîte de dialogue.

Cette méthode expose le même comportement que le mécanisme interne de surveillance de fermeture (close watcher en anglais) du dialogue.

Syntaxe

requestClose()
requestClose(returnValue)

Paramètres

returnValue Facultatif: Chaîne de caractères représentant la nouvelle valeur de HTMLDialogElement.returnValue de la boîte de dialogue.

L'empêchement de la fermeture de la boîte de dialogue est démontré avec une case à cocher.

HTML

html

<dialog id="dialogue">
  <div>
    <label
      ><input type="checkbox" id="empecher-fermeture" /> Annuler la
      fermeture</label
    >
  </div>
  <button type="button" id="fermer">Fermer</button>
  <button type="button" id="fermer-avec-valeur">
    Fermer avec valeur de retour
  </button>
</dialog>

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

<pre id="journal"></pre>

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

const elementJournal = document.getElementById("journal");
function journaliser(texte) {
  elementJournal.innerText = `${elementJournal.innerText}${texte}\n`;
  elementJournal.scrollTop = elementJournal.scrollHeight;
}

const dialogue = document.getElementById("dialogue");
const boutonOuvrir = document.getElementById("ouvrir");
const boutonFermer = document.getElementById("fermer");
const boutonFermerAvecValeur = document.getElementById("fermer-avec-valeur");
const caseEmpecherFermeture = document.getElementById("empecher-fermeture");

// Le bouton Ouvrir ouvre une boîte de dialogue modale
boutonOuvrir.addEventListener("click", () => {
  // Réinitialiser la valeur de retour
  dialogue.returnValue = "";
  // Afficher la boîte de dialogue
  dialogue.showModal();
});

// Le bouton Fermer ferme la boîte de dialogue
boutonFermer.addEventListener("click", () => {
  dialogue.requestClose();
});

// Le bouton Fermer avec valeur de retour ferme la boîte de dialogue avec une valeur de retour
boutonFermerAvecValeur.addEventListener("click", () => {
  dialogue.requestClose("des valeurs de retour");
});

// Déclenché lorsque requestClose() est appelé
// Empêcher la fermeture de la boîte de dialogue en appelant event.preventDefault()
dialogue.addEventListener("cancel", (event) => {
  if (caseEmpecherFermeture.checked) {
    journaliser("Fermeture de la boîte de dialogue annulée");
    event.preventDefault();
  }
});

// l'évènement "cancel" n'est pas empêché, la boîte de dialogue se ferme
dialogue.addEventListener("close", () => {
  journaliser(
    `Boîte de dialogue fermée. Valeur de retour : "${dialogue.returnValue}"`,
  );
});