new StorageEvent() — Methode · JavaScript-Referenz

Signatur

new StorageEvent(type, options)

Beschreibung

Mit new StorageEvent() legt man manuell ein Ereignisobjekt vom Typ StorageEvent an. Der Browser erzeugt solche Ereignisse normalerweise selbst: Ändert ein Tab oder Fenster den localStorage, bekommen alle anderen Dokumente mit demselben Ursprung ein storage-Ereignis. Das Dokument, das die Änderung vorgenommen hat, erhält dagegen kein Ereignis.

Den Konstruktor braucht man vor allem in zwei Fällen: Unit-Tests, in denen man einen storage-Listener prüfen will, ohne zwei Tabs zu öffnen, und die Benachrichtigung im selben Tab. Hier schreibt der eigene Code in den Speicher und löst anschließend per window.dispatchEvent() ein passendes Ereignis aus, damit derselbe Handler auch lokale Änderungen verarbeitet.

Im Objekt options gibt man die Eigenschaften key, oldValue, newValue, url und storageArea an. Zusätzlich sind die allgemeinen Ereignis-Optionen aus EventInit erlaubt (bubbles, cancelable, composed). Alle diese Eigenschaften sind danach nur lesbar.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, unterscheidet Groß- und Kleinschreibung. Der Browser verwendet dafür immer `"storage"`.
$options	object	{}	Optionales Objekt mit den Werten des Ereignisses. Enthält die `EventInit`-Felder (`bubbles`, `cancelable`, `composed`) sowie die folgenden Felder.
$options.key	string \| null	null	Schlüssel, der geändert wurde. `null` bedeutet, dass der Speicher mit `clear()` geleert wurde.
$options.oldValue	string \| null	null	Wert vor der Änderung. `null`, wenn der Schlüssel neu ist.
$options.newValue	string \| null	null	Wert nach der Änderung. `null`, wenn der Schlüssel entfernt wurde.
$options.url	string	""	URL des Dokuments, dessen Speicher geändert wurde.
$options.storageArea	Storage \| null	null	Das betroffene `Storage`-Objekt, also `localStorage` oder `sessionStorage`.

Rückgabewert

Typ

StorageEvent

Beschreibung

Ein neues StorageEvent-Objekt mit den übergebenen Werten. Es kann mit dispatchEvent() ausgelöst werden.

Beispiele

Einfaches StorageEvent erzeugen und auslesen

const event = new StorageEvent('storage', {
  key: 'theme',
  oldValue: 'light',
  newValue: 'dark',
  url: location.href,
  storageArea: localStorage
});

console.log(event.type, event.key, event.oldValue, '→', event.newValue);
console.log(event.storageArea === localStorage);

storage theme light → dark true

Änderungen auch im selben Tab melden

const handleStorage = (e) => {
  if (e.key === 'theme') {
    document.documentElement.dataset.theme = e.newValue ?? 'light';
    console.log(`Theme gewechselt: ${e.oldValue} → ${e.newValue}`);
  }
};
window.addEventListener('storage', handleStorage);

// Hilfsfunktion: schreibt den Wert und benachrichtigt auch den eigenen Tab
const setItemAndNotify = (key, value) => {
  const oldValue = localStorage.getItem(key);
  localStorage.setItem(key, value);
  window.dispatchEvent(new StorageEvent('storage', {
    key,
    oldValue,
    newValue: value,
    url: location.href,
    storageArea: localStorage
  }));
};

localStorage.setItem('theme', 'light');
setItemAndNotify('theme', 'dark');

Theme gewechselt: light → dark

Listener im Test prüfen (Abmelden per clear())

let loggedOut = false;

const onStorage = (e) => {
  // key === null bedeutet: storage.clear() wurde aufgerufen
  if (e.storageArea === localStorage && (e.key === null || e.key === 'token') && e.newValue === null) {
    loggedOut = true;
  }
};
window.addEventListener('storage', onStorage);

window.dispatchEvent(new StorageEvent('storage', {
  key: null,
  storageArea: localStorage
}));

console.log('Abgemeldet:', loggedOut);
window.removeEventListener('storage', onStorage);

Abgemeldet: true

// Wichtig · Fallstricke

Nur ein Ereignisobjekt: Ein selbst erzeugtes StorageEvent ändert den Speicher nicht und geht nicht an andere Tabs. Es erreicht nur die Listener des Ziels, auf dem man dispatchEvent() aufruft.
Kein Ereignis im eigenen Tab: Das echte storage-Ereignis gibt der Browser nur in anderen Dokumenten desselben Ursprungs aus. Eine häufige Fehlerquelle ist, auf ein Ereignis nach dem eigenen setItem() zu warten.
event.isTrusted ist bei selbst ausgelösten Ereignissen false. Echte Browser-Ereignisse lassen sich daran von simulierten unterscheiden.
Werte werden nicht in Text umgewandelt, wenn sie null sind. Andere Typen, zum Beispiel Zahlen, werden in Strings umgewandelt. Bei storageArea ist nur ein Storage-Objekt oder null erlaubt, sonst wirft der Konstruktor einen TypeError.
Für die Kommunikation zwischen Tabs ist BroadcastChannel oft besser geeignet, weil es beliebige Daten ohne Umweg über den Speicher überträgt.
Den Konstruktor unterstützen alle aktuellen Browser. Veraltete Engines kannten nur die überholte Methode initStorageEvent(). In Node.js gibt es StorageEvent nicht, dort braucht man für Tests jsdom oder eine vergleichbare Umgebung.

Siehe auch

Window.localStorage Window.sessionStorage EventTarget.dispatchEvent() BroadcastChannel new CommandEvent()