StorageEvent.key — Eigenschaft · JavaScript-Referenz

Signatur

StorageEvent.key

Beschreibung

Die schreibgeschützte Eigenschaft key des StorageEvent gibt als Zeichenkette den Schlüssel an, dessen Wert im Web Storage gesetzt, geändert oder entfernt wurde. Hat die Änderung durch Storage.clear() alle Einträge gelöscht, ist key null.

Das storage-Event wird nicht in dem Dokument ausgelöst, das die Änderung vorgenommen hat, sondern in allen anderen Fenstern, Tabs und iframes desselben Ursprungs (Origin), die auf denselben Speicherbereich zugreifen. Deshalb eignet sich key gut, um zwischen Tabs zu synchronisieren, z. B. Login-/Logout-Status, Theme-Einstellungen oder Warenkorbinhalte.

In der Regel wertet man key zusammen mit oldValue, newValue und storageArea aus: Anhand des Schlüssels entscheidet man, ob die Änderung für die eigene Anwendung relevant ist, und anhand der Werte, was sich geändert hat.

Rückgabewert

Typ

string | null

Beschreibung

Der Schlüssel des geänderten Eintrags, oder null, wenn die Änderung durch clear() ausgelöst wurde.

Beispiele

Änderungen aus anderen Tabs protokollieren

window.addEventListener('storage', (event) => {
  if (event.key === null) {
    console.log('Speicher wurde komplett geleert');
    return;
  }
  console.log(`Schlüssel "${event.key}": ${event.oldValue} → ${event.newValue}`);
});

// In einem ANDEREN Tab desselben Origins ausführen:
// localStorage.setItem('theme', 'dark');

Schlüssel "theme": light → dark

Logout in allen Tabs synchronisieren

const AUTH_KEY = 'authToken';

const onStorage = (event) => {
  // Nur auf den relevanten Schlüssel reagieren (oder auf clear())
  if (event.storageArea !== localStorage) return;
  if (event.key === AUTH_KEY || event.key === null) {
    if (!localStorage.getItem(AUTH_KEY)) {
      console.log('In anderem Tab abgemeldet – leite weiter');
      window.location.assign('/login');
    }
  }
};

window.addEventListener('storage', onStorage);

// Später, z. B. beim Verlassen der Ansicht:
// window.removeEventListener('storage', onStorage);

In anderem Tab abgemeldet – leite weiter

Per on-Property und selbst erzeugtem Event testen

window.onstorage = (event) => {
  console.log('key:', event.key);
};

// Synthetisches Event, z. B. für Unit-Tests
window.dispatchEvent(new StorageEvent('storage', {
  key: 'cart',
  oldValue: '[]',
  newValue: '["apfel"]',
  storageArea: localStorage
}));

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

key: cart key: null

// Wichtig · Fallstricke

Nicht im auslösenden Tab: Das Event wird nur in anderen Dokumenten desselben Origins ausgelöst. Wer im selben Tab reagieren will, muss die Logik direkt nach setItem() aufrufen oder ein eigenes Event versenden.
null prüfen: Nach clear() ist key null – ein einfacher Vergleich wie event.key.startsWith(...) wirft dann einen TypeError.
Kein Event ohne Änderung: Wird ein Schlüssel auf denselben Wert gesetzt, feuern Browser in der Regel kein Event.
sessionStorage: Da sessionStorage an den Tab gebunden ist, kommen Events dort meist nur zwischen iframes desselben Tabs an. Mit storageArea lässt sich unterscheiden, welcher Speicher betroffen ist.
Sicherheit: Werte aus dem Storage können von jedem Skript desselben Origins geschrieben werden – vor der Verwendung (z. B. in innerHTML) validieren bzw. escapen.
Die Eigenschaft wird von allen modernen Browsern unterstützt; im privaten Modus älterer Safari-Versionen war Web Storage teils eingeschränkt.

Siehe auch

StorageEvent.url StorageEvent.newValue StorageEvent.oldValue StorageEvent.storageArea KeyboardEvent.key