CloseWatcher: close — Ereignis · JavaScript-Referenz

Signatur

closeWatcher.addEventListener("close", handler)

Beschreibung

Das close-Ereignis ist das zentrale Ereignis der CloseWatcher-API. Es signalisiert, dass eine Komponente wie ein eigenes Modal, ein Seitenpanel, ein Popover oder ein Menü jetzt geschlossen werden soll. Schließanforderungen können aus unterschiedlichen Quellen kommen: die Esc-Taste auf dem Desktop, die Zurück-Geste oder -Taste unter Android oder ein programmatischer Aufruf von closeWatcher.close() bzw. closeWatcher.requestClose(). So muss man nicht für jede Plattform eigene Tastatur- oder Gesten-Listener schreiben.

Die Reihenfolge ist fest vorgegeben: Bei requestClose() und bei Schließanforderungen des Nutzers wird zuerst cancel ausgelöst. Nur wenn dessen Handler nicht event.preventDefault() aufruft, folgt close. closeWatcher.close() überspringt cancel und löst close sofort aus. Wurde close einmal ausgelöst, ist der Watcher verbraucht. Er reagiert danach auf keine weiteren Anforderungen mehr. Für eine erneute Öffnung braucht man einen neuen CloseWatcher.

Den Handler registriert man mit addEventListener("close", handler) oder über die Eigenschaft onclose. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Es wird nicht weitergereicht (bubbelt nicht) und lässt sich nicht abbrechen. Im Handler räumt man üblicherweise die Oberfläche auf: Element ausblenden, Fokus zurücksetzen, Zustand aktualisieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"close"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie erhält ein einfaches `Event`-Objekt, dessen `target` der `CloseWatcher` ist.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignis selbst ist ein Event (cancelable: false, bubbles: false).

Beispiele

Eigenes Seitenpanel per Esc bzw. Zurück-Geste schließen

const panel = document.querySelector('#sidepanel');

const openPanel = () => {
  panel.hidden = false;
  // Pro Öffnung ein neuer Watcher, denn nach close ist er verbraucht
  const watcher = new CloseWatcher();

  watcher.addEventListener('close', () => {
    panel.hidden = true;
    console.log('Panel geschlossen');
  });

  // Schließen-Button nutzt denselben Weg
  panel.querySelector('.close-btn').onclick = () => watcher.requestClose();
};

document.querySelector('#open').addEventListener('click', openPanel);

Panel geschlossen

Zusammenspiel mit cancel: ungespeicherte Änderungen

const editor = document.querySelector('#editor');
let dirty = false;
editor.addEventListener('input', () => { dirty = true; });

const watcher = new CloseWatcher();

watcher.oncancel = (event) => {
  // Bei ungespeicherten Änderungen nachfragen
  if (dirty && !confirm('Änderungen verwerfen?')) {
    event.preventDefault(); // close wird dann NICHT ausgelöst
  }
};

watcher.onclose = () => {
  editor.closest('dialog, .modal').hidden = true;
  console.log('Editor geschlossen');
};

Editor geschlossen (nur wenn cancel nicht abgebrochen wurde)

on-Property und Listener entfernen

const watcher = new CloseWatcher();

const onClose = () => console.log('close per addEventListener');
watcher.addEventListener('close', onClose);
watcher.removeEventListener('close', onClose); // wieder entfernt

// Alternative: on-Property (ersetzt vorherigen onclose-Handler)
watcher.onclose = () => console.log('close per onclose');

// close() überspringt cancel und löst close direkt aus
watcher.close();

close per onclose

Feature-Erkennung mit Fallback

const makeClosable = (el) => {
  const hide = () => { el.hidden = true; };

  if ('CloseWatcher' in window) {
    const watcher = new CloseWatcher();
    watcher.addEventListener('close', hide);
    return () => watcher.requestClose();
  }

  // Fallback: nur Esc-Taste
  const onKey = (e) => {
    if (e.key === 'Escape') {
      hide();
      document.removeEventListener('keydown', onKey);
    }
  };
  document.addEventListener('keydown', onKey);
  return hide;
};

const close = makeClosable(document.querySelector('#toast'));

// Wichtig · Fallstricke

Browser-Unterstützung: CloseWatcher gibt es bisher nur in Chromium-basierten Browsern (ab Version 126). Firefox und Safari unterstützen die API noch nicht. Deshalb vorher immer mit 'CloseWatcher' in window prüfen und einen Fallback bereithalten, etwa einen keydown-Listener für Esc.
Nur ein Einsatz: Nach close (oder destroy()) ist der Watcher inaktiv. Für jede neue Öffnung einen neuen CloseWatcher anlegen.
Nutzeraktivierung: Legt man ohne vorherige Nutzerinteraktion mehrere Watcher an, fasst der Browser sie zu einer Gruppe zusammen. Eine einzige Zurück-Geste kann dann mehrere Watcher gleichzeitig schließen. Watcher daher möglichst direkt in einem Klick-Handler erzeugen.
cancel ist nicht garantiert: Ohne vorherige Nutzeraktivierung darf der Browser cancel überspringen und direkt close auslösen. So wird verhindert, dass Seiten den Nutzer „festhalten“. Wichtige Aufräumarbeiten gehören deshalb immer in den close-Handler.
close() löst cancel nie aus, requestClose() dagegen schon.
Für native <dialog>-Elemente und das popover-Attribut ist CloseWatcher nicht nötig, weil diese das Verhalten schon eingebaut haben.

Siehe auch

CloseWatcher CloseWatcher: cancel CloseWatcher.prototype.requestClose() CloseWatcher.prototype.close() CloseWatcher.prototype.destroy() Element: mousemove