HTMLDialogElement.requestClose() — Methode · JavaScript-Referenz

Signatur

HTMLDialogElement.prototype.requestClose(returnValue)

Beschreibung

Mit requestClose() bitten Sie einen geöffneten <dialog> darum, sich zu schließen. Anders als bei close() wird der Dialog nicht sofort geschlossen. Zuerst löst der Browser am Dialog ein abbrechbares cancel-Event aus. Ruft kein Listener event.preventDefault() auf, wird der Dialog geschlossen und danach das close-Event ausgelöst.

Programmatisches Schließen läuft damit genauso ab wie das Schließen durch den Nutzer, etwa mit der Esc-Taste, einer Schließgeste oder, bei closedby="any", einem Klick auf den Hintergrund. Die Logik für Rückfragen wie „Ungespeicherte Änderungen verwerfen?“ steht so an einer einzigen Stelle, im cancel-Handler, und gilt für alle Wege, auf denen der Dialog geschlossen wird.

Übergeben Sie das optionale Argument returnValue, wird es beim tatsächlichen Schließen in dialog.returnValue geschrieben. So kann der aufrufende Code auswerten, wie der Dialog beendet wurde. Wenn der Dialog nicht geöffnet ist, bewirkt der Aufruf nichts.

Verwenden Sie requestClose(), wenn eigene Schaltflächen wie „Abbrechen“ oder „×“ dieselben Prüfungen durchlaufen sollen wie die Esc-Taste. Soll der Dialog ohne Rückfrage in jedem Fall zugehen, zum Beispiel nach erfolgreichem Speichern, ist close() die richtige Wahl.

Parameter

Name	Typ	Default	Beschreibung
$returnValue	string		Optionaler Text, der beim tatsächlichen Schließen in `dialog.returnValue` übernommen wird. Fehlt das Argument, bleibt der bisherige `returnValue` erhalten. Wird das Schließen im `cancel`-Handler verhindert, ändert sich `returnValue` nicht.

Beispiele

Schließen verhindern bei ungespeicherten Änderungen

// HTML: <dialog id="editor"><form><textarea name="text"></textarea>
//        <button type="button" id="abbrechen">Abbrechen</button></form></dialog>
const dialog = document.querySelector('#editor');
const textarea = dialog.querySelector('textarea');
let geaendert = false;

textarea.addEventListener('input', () => { geaendert = true; });

// Gilt für die Esc-Taste UND für requestClose()
dialog.addEventListener('cancel', (event) => {
  if (geaendert && !confirm('Ungespeicherte Änderungen verwerfen?')) {
    event.preventDefault(); // Dialog bleibt offen
  }
});

dialog.querySelector('#abbrechen').addEventListener('click', () => {
  dialog.requestClose(); // dieselbe Prüfung wie bei Esc
});

dialog.showModal();

Rückgabewert übergeben und auswerten

const dialog = document.querySelector('dialog');

dialog.addEventListener('close', () => {
  console.log('Dialog geschlossen mit:', dialog.returnValue);
});

dialog.showModal();

// z. B. in einem Klick-Handler einer „Später“-Schaltfläche
dialog.requestClose('spaeter');

Dialog geschlossen mit: spaeter

Unterschied zwischen close() und requestClose()

const dialog = document.querySelector('dialog');

dialog.addEventListener('cancel', (e) => {
  console.log('cancel ausgelöst');
  e.preventDefault();
});

dialog.showModal();

dialog.requestClose();
console.log('offen nach requestClose():', dialog.open);

dialog.close(); // kein cancel, schließt immer
console.log('offen nach close():', dialog.open);

cancel ausgelöst offen nach requestClose(): true offen nach close(): false

Mit Fallback für ältere Browser

const schliessenAnfragen = (dialog, wert) => {
  if (typeof dialog.requestClose === 'function') {
    dialog.requestClose(wert);
    return;
  }
  // Fallback: cancel-Event selbst auslösen
  const ev = new Event('cancel', { cancelable: true });
  if (dialog.dispatchEvent(ev)) {
    dialog.close(wert);
  }
};

schliessenAnfragen(document.querySelector('dialog'), 'abgebrochen');

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode ist recht neu: Chrome/Edge ab 134, Firefox ab 139, Safari ab 18.4. Prüfen Sie vor dem Aufruf mit 'requestClose' in HTMLDialogElement.prototype und sehen Sie einen Fallback vor, zum Beispiel ein eigenes cancel-Event per dispatchEvent und anschließend close().
Immer abbrechbar: Beim Esc-Schließen können Browser wiederholtes preventDefault() ohne Nutzeraktivierung ignorieren, damit Nutzer nicht in einem Dialog festsitzen. Das cancel-Event von requestClose() ist dagegen immer abbrechbar.
Kein Effekt bei geschlossenem Dialog: Ist dialog.open auf false, werden weder cancel noch close ausgelöst.
closedby-Attribut: requestClose() funktioniert auch bei closedby="none". Das Attribut regelt nur, wie der Nutzer den Dialog schließen kann, nicht den programmatischen Aufruf.
Asynchroner Ablauf: Das close-Event wird in eine Warteschlange gestellt und erst später ausgelöst. dialog.open ist aber direkt nach dem Aufruf bereits false, sofern das Schließen nicht verhindert wurde.
Rufen Sie requestClose() nicht innerhalb eines eigenen cancel-Handlers erneut auf. Das führt zu verschachtelten Events und zu schwer nachvollziehbarem Verhalten.

Siehe auch

HTMLDialogElement HTMLDialogElement.close() HTMLDialogElement.showModal() HTMLDialogElement.show() HTMLDialogElement.returnValue HTMLDialogElement.open CloseWatcher