StorageEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface StorageEvent extends Event

Beschreibung

Das Interface StorageEvent beschreibt das Ereignisobjekt des storage-Events. Der Browser löst es auf window aus, sobald ein anderes Dokument desselben Ursprungs einen Speicherbereich ändert, auf den auch das aktuelle Fenster zugreift. Das Dokument, das die Änderung selbst vornimmt, erhält dagegen kein Event.

Damit eignet sich StorageEvent gut, um mehrere Tabs miteinander abzustimmen. Typische Fälle sind eine Abmeldung in allen Tabs, gemeinsame Einstellungen wie ein Dunkelmodus oder ein Warenkorb, der überall aktuell bleibt. Welche Änderung passiert ist, beschreiben die schreibgeschützten Eigenschaften:

key: der geänderte Schlüssel. Bei clear() ist er null.
oldValue: der vorherige Wert. Bei einem neu angelegten Schlüssel ist er null.
newValue: der neue Wert. Bei removeItem() oder clear() ist er null.
url: die URL des Dokuments, das die Änderung ausgelöst hat.
storageArea: das betroffene Storage-Objekt, also localStorage oder sessionStorage.

Mit dem Konstruktor new StorageEvent(type, options) lassen sich eigene Instanzen erzeugen, etwa für Tests oder um ein Event von Hand im selben Tab auszulösen. Außerdem gibt es die veraltete Methode initStorageEvent(). Sie sollte nicht mehr verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, in der Praxis `"storage"`.
$options	object	{}	Optionales Objekt mit den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`) sowie `key`, `oldValue` und `newValue` (jeweils `string\|null`, Standard `null`), `url` (`string`, Standard `""`) und `storageArea` (`Storage\|null`, Standard `null`).

Rückgabewert

Typ

StorageEvent

Beschreibung

Eine neue StorageEvent-Instanz, wenn der Konstruktor aufgerufen wird. Im Handler bekommt man das Objekt vom Browser übergeben.

Beispiele

Änderungen aus anderen Tabs protokollieren (addEventListener)

window.addEventListener('storage', (event) => {
  const bereich = event.storageArea === localStorage ? 'localStorage' : 'sessionStorage';
  console.log(`[${bereich}] ${event.key}: ${event.oldValue} → ${event.newValue}`);
  console.log('Ausgelöst von:', event.url);
});

// In einem ANDEREN Tab desselben Ursprungs:
// localStorage.setItem('theme', 'dark');

[localStorage] theme: light → dark Ausgelöst von: https://example.com/einstellungen

Abmeldung in allen Tabs gleichzeitig (onstorage-Property)

const logoutEverywhere = () => {
  localStorage.removeItem('authToken');
  window.location.href = '/login';
};

window.onstorage = (event) => {
  // removeItem() oder clear() in einem anderen Tab
  if ((event.key === 'authToken' || event.key === null) && event.newValue === null) {
    console.log('In einem anderen Tab abgemeldet – leite weiter.');
    window.location.href = '/login';
  }
};

// Handler später wieder entfernen:
// window.onstorage = null;

In einem anderen Tab abgemeldet – leite weiter.

JSON-Warenkorb abgleichen und Listener wieder entfernen

const renderCart = (items) => console.log(`Warenkorb: ${items.length} Artikel`);

const onCartChange = (event) => {
  if (event.storageArea !== localStorage || event.key !== 'cart') return;
  const items = event.newValue ? JSON.parse(event.newValue) : [];
  renderCart(items);
};

window.addEventListener('storage', onCartChange);

// z. B. beim Verlassen der Ansicht aufräumen:
const cleanup = () => window.removeEventListener('storage', onCartChange);

Warenkorb: 3 Artikel

StorageEvent manuell erzeugen (Test / gleicher Tab)

const setAndNotify = (key, value) => {
  const oldValue = localStorage.getItem(key);
  localStorage.setItem(key, value);
  // Der eigene Tab bekommt sonst kein Event – daher selbst auslösen
  window.dispatchEvent(new StorageEvent('storage', {
    key,
    oldValue,
    newValue: value,
    url: location.href,
    storageArea: localStorage
  }));
};

window.addEventListener('storage', (e) => console.log(e.key, '=', e.newValue));
setAndNotify('lang', 'de');

lang = de

// Wichtig · Fallstricke

Nicht im auslösenden Tab: Das Dokument, das den Speicher ändert, erhält kein storage-Event. Um auch lokal zu reagieren, ruft man die Logik direkt auf oder löst selbst ein StorageEvent aus.
Nur bei echten Änderungen: Setzt setItem() einen Wert, der schon genauso gespeichert ist, wird kein Event ausgelöst.
clear(): Hier sind key, oldValue und newValue alle null. Das sollte man ausdrücklich behandeln.
sessionStorage: Änderungen erreichen nur Dokumente mit demselben Top-Level-Browsing-Kontext, zum Beispiel iframes im selben Tab. Andere Tabs werden nicht benachrichtigt.
Werte sind immer Strings: Objekte müssen mit JSON.stringify gespeichert und mit JSON.parse gelesen werden. Das Parsen in try/catch absichern, denn fremde Tabs oder Erweiterungen können ungültige Daten schreiben.
Sicherheit: newValue stammt von beliebigem Code desselben Ursprungs. Es darf nie ungeprüft in innerHTML oder eval landen, sonst droht XSS.
Kompatibilität: In allen modernen Browsern unterstützt. Im privaten Modus oder bei gesperrtem Speicher kann localStorage fehlen oder beim Schreiben einen Fehler werfen. Für Nachrichten zwischen Tabs ohne Speicherumweg ist BroadcastChannel oft die bessere Wahl.
initStorageEvent() ist veraltet. Stattdessen den Konstruktor verwenden.

Siehe auch

Storage Window.localStorage Window.sessionStorage BroadcastChannel Event EventTarget.dispatchEvent()