BeforeUnloadEvent.returnValue — Eigenschaft · JavaScript-Referenz

Signatur

BeforeUnloadEvent.returnValue

Beschreibung

Die Eigenschaft returnValue des BeforeUnloadEvent-Interfaces ist ein Altmechanismus, um das Verlassen einer Seite abzufangen. Setzt man sie innerhalb eines beforeunload-Handlers auf einen truthy Wert (historisch einen String), zeigt der Browser einen eigenen Dialog an, in dem der Benutzer bestätigen muss, dass er die Seite wirklich verlassen oder neu laden möchte.

Typischer Einsatz sind Formulare oder Editoren mit ungespeicherten Änderungen: Nur solange tatsächlich Daten verloren gehen würden, sollte der Dialog ausgelöst werden. Der Standardwert ist ein leerer String ""; ein leerer bzw. falsy Wert löst keinen Dialog aus.

Der im String angegebene Text wird von modernen Browsern nicht mehr angezeigt – sie zeigen aus Sicherheitsgründen (Schutz vor Betrugsseiten) stets einen generischen Standardtext. Der empfohlene, standardkonforme Weg ist heute event.preventDefault(); returnValue wird zusätzlich gesetzt, um ältere Browser (v. a. ältere Chromium-Versionen) abzudecken.

Rückgabewert

Typ

string

Beschreibung

Der aktuell gesetzte Wert (Standard: ""). Ein truthy Wert signalisiert dem Browser, einen Bestätigungsdialog anzuzeigen. Beim Setzen wird der Wert in einen String umgewandelt.

Beispiele

Warnung bei ungespeicherten Formulardaten (addEventListener)

const form = document.querySelector('#profil-form');
let istGeaendert = false;

form.addEventListener('input', () => {
  istGeaendert = true;
});

const beiVerlassen = (event) => {
  if (!istGeaendert) return;
  // Moderner, standardkonformer Weg
  event.preventDefault();
  // Fallback für ältere Browser
  event.returnValue = true;
};

window.addEventListener('beforeunload', beiVerlassen);

form.addEventListener('submit', () => {
  // Nach dem Absenden keine Warnung mehr
  istGeaendert = false;
  window.removeEventListener('beforeunload', beiVerlassen);
});

(Beim Schließen des Tabs mit geänderten Daten erscheint der Browser-Dialog „Seite verlassen?“)

Listener nur bei Bedarf registrieren

const warnung = (event) => {
  event.preventDefault();
  event.returnValue = '';
  // Hinweis: '' ist falsy – in älteren Chromium-Versionen reicht nur preventDefault nicht,
  // daher dort einen String setzen:
  event.returnValue = 'Ungespeicherte Änderungen';
};

const setzeUngespeichert = (aktiv) => {
  if (aktiv) {
    window.addEventListener('beforeunload', warnung);
  } else {
    window.removeEventListener('beforeunload', warnung);
  }
};

// Editor meldet Änderungen
setzeUngespeichert(true);
// ... nach erfolgreichem Speichern
setzeUngespeichert(false);

Legacy-Variante über die on-Property

window.onbeforeunload = (event) => {
  const text = 'Sie haben ungespeicherte Änderungen.';
  event.returnValue = text; // für ältere Browser
  return text;              // für sehr alte Browser
};

// Deaktivieren
// window.onbeforeunload = null;

// Wichtig · Fallstricke

Eigener Text wird ignoriert: Chrome (ab 51), Firefox (ab 44) und Safari (ab 9.1) zeigen nur einen generischen Standardtext an.
Benutzerinteraktion nötig: Browser zeigen den Dialog nur, wenn der Benutzer zuvor mit der Seite interagiert hat (sticky activation). Ohne Klick/Eingabe erscheint nichts.
Falsy Werte: Wird returnValue auf "" gesetzt, zeigt z. B. Chrome keinen Dialog. Für breite Kompatibilität preventDefault() und einen truthy returnValue kombinieren.
Performance: Ein registrierter beforeunload-Listener kann den Back/Forward-Cache (bfcache) verhindern. Listener daher nur bei ungespeicherten Änderungen hinzufügen und danach wieder entfernen.
Mobil unzuverlässig: Auf Mobilgeräten wird beforeunload oft nicht ausgelöst (z. B. beim Wechsel der App). Zum Sichern von Daten besser visibilitychange/pagehide und navigator.sendBeacon() verwenden.
Die Eigenschaft gilt als veraltet (Legacy); sie bleibt aber aus Kompatibilitätsgründen in allen Browsern unterstützt.

Siehe auch

BeforeUnloadEvent PerformanceTiming.redirectEnd Event.returnValue HTMLDialogElement.returnValue StorageEvent.newValue