StorageEvent.oldValue — Eigenschaft · JavaScript-Referenz

Signatur

StorageEvent.oldValue

Beschreibung

Die schreibgeschützte Eigenschaft oldValue des StorageEvent enthält den Wert, den der geänderte Schlüssel vor der Änderung hatte. Zusammen mit key und newValue erkennt man daran genau, was sich im Web Storage geändert hat.

Das storage-Event wird auf window ausgelöst, allerdings nur in anderen Dokumenten (Tabs, Fenstern, iframes) desselben Ursprungs. Das Dokument, das die Änderung selbst vorgenommen hat, bekommt das Event nicht. Deshalb eignet sich oldValue gut, um Zustände über mehrere Tabs hinweg abzugleichen, etwa bei Logout, Theme-Wechsel oder Warenkorb-Änderungen.

Welcher Wert drinsteht, hängt von der Art der Änderung ab:

Neuer Schlüssel (vorher nicht vorhanden): oldValue ist null.
Wert überschrieben: oldValue enthält den vorherigen String.
Schlüssel entfernt (removeItem): oldValue enthält den letzten Wert, newValue ist null.
clear(): key, oldValue und newValue sind alle null.

Rückgabewert

Typ

string | null

Beschreibung

Der vorherige Wert als String oder null, wenn der Schlüssel neu angelegt wurde oder der Speicher mit clear() geleert wurde.

Beispiele

Änderungen aus anderen Tabs protokollieren (addEventListener)

// In Tab A ausführen:
window.addEventListener('storage', (event) => {
  if (event.storageArea !== localStorage) return;
  console.log(`Schlüssel: ${event.key}`);
  console.log(`Alt: ${event.oldValue}`);
  console.log(`Neu: ${event.newValue}`);
});

// In Tab B (gleicher Ursprung) ausführen:
// localStorage.setItem('theme', 'light');
// localStorage.setItem('theme', 'dark');

Schlüssel: theme Alt: null Neu: light Schlüssel: theme Alt: light Neu: dark

Art der Änderung erkennen

const describeChange = ({ key, oldValue, newValue }) => {
  if (key === null) return 'Speicher wurde komplett geleert';
  if (oldValue === null) return `"${key}" neu angelegt: ${newValue}`;
  if (newValue === null) return `"${key}" entfernt (war: ${oldValue})`;
  return `"${key}" geändert: ${oldValue} → ${newValue}`;
};

const onStorage = (event) => console.log(describeChange(event));
window.onstorage = onStorage;

// Später wieder abmelden:
// window.onstorage = null;

"cart" geändert: ["a"] → ["a","b"]

JSON-Warenkorb: hinzugefügte Artikel ermitteln

const parse = (value) => {
  try { return JSON.parse(value) ?? []; } catch { return []; }
};

const handler = (event) => {
  if (event.key !== 'cart') return;
  const before = parse(event.oldValue);
  const after = parse(event.newValue);
  const added = after.filter((item) => !before.includes(item));
  console.log('In anderem Tab hinzugefügt:', added);
};

window.addEventListener('storage', handler);
// Aufräumen, z. B. beim Unmount einer Komponente:
// window.removeEventListener('storage', handler);

In anderem Tab hinzugefügt: ["b"]

// Wichtig · Fallstricke

Kein Event im eigenen Tab: Das Dokument, das setItem/removeItem aufruft, bekommt kein storage-Event. Für die Kommunikation innerhalb desselben Tabs braucht man eigene Events, für mehrere Tabs eignet sich auch BroadcastChannel.
Immer Strings: oldValue ist ein String oder null. Objekte muss man mit JSON.parse umwandeln und dabei null sowie ungültiges JSON abfangen.
Gleicher Wert: Wird ein Schlüssel auf denselben Wert gesetzt, lösen Browser laut Spezifikation kein Event aus.
clear(): Die alten Werte stehen dann nicht zur Verfügung, weil oldValue null ist. Wer sie braucht, muss sie selbst zwischenspeichern.
sessionStorage: Events kommen nur in Kontexten an, die sich dieselbe Sitzung teilen (z. B. iframes im selben Tab), nicht in anderen Tabs.
Sicherheit: Werte aus dem Storage nicht ungeprüft per innerHTML ausgeben. Andere Skripte desselben Ursprungs können sie verändert haben (XSS-Gefahr).
Die Eigenschaft wird von allen modernen Browsern unterstützt und ist schreibgeschützt.

Siehe auch

PerformanceTiming.domainLookupEnd StorageEvent.newValue StorageEvent.url StorageEvent.key StorageEvent.storageArea