Signatur
Beschreibung
Die Eigenschaft newValue eines StorageEvent-Objekts enthält den Wert, den ein Schlüssel in localStorage oder sessionStorage nach der Änderung besitzt. Zusammen mit key und oldValue lässt sich so genau nachvollziehen, was sich geändert hat.
Das storage-Ereignis wird nur in anderen Dokumenten (Tabs, Fenstern, iframes) desselben Ursprungs ausgelöst, nicht in dem Dokument, das die Änderung vorgenommen hat. Deshalb eignet sich newValue gut zur Synchronisation zwischen Tabs, etwa für Abmeldungen, Designwechsel (hell/dunkel) oder Warenkorbzustände.
Der Wert ist immer ein string, weil Web Storage nur Strings speichert. Strukturierte Daten müssen daher mit JSON.parse() zurückverwandelt werden. Wird ein Schlüssel über removeItem() gelöscht oder der ganze Speicher mit clear() geleert, ist newValue null.
Rückgabewert
null, wenn der Schlüssel entfernt oder der Speicher per clear() geleert wurde.Beispiele
Änderungen aus anderen Tabs protokollieren
// In Tab A ausführen:
window.addEventListener('storage', (event) => {
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', 'dark');Abmeldung über alle Tabs synchronisieren
window.addEventListener('storage', (event) => {
// Token wurde in einem anderen Tab entfernt
if (event.key === 'authToken' && event.newValue === null) {
console.log('Sitzung beendet – Weiterleitung zur Anmeldung');
window.location.assign('/login');
}
});
// Im anderen Tab beim Abmelden:
// localStorage.removeItem('authToken');JSON-Daten sicher auswerten
const parseSafe = (value) => {
if (value === null) return null;
try {
return JSON.parse(value);
} catch {
return null;
}
};
window.onstorage = (event) => {
if (event.key !== 'cart') return;
const cart = parseSafe(event.newValue) ?? [];
console.log(`Warenkorb enthält jetzt ${cart.length} Artikel`);
};
// Anderer Tab:
// localStorage.setItem('cart', JSON.stringify([{ id: 1 }, { id: 2 }]));clear() erkennen
window.addEventListener('storage', (event) => {
// Bei clear() sind key, oldValue und newValue alle null
if (event.key === null) {
console.log('Gesamter Speicher wurde geleert');
return;
}
console.log(`${event.key} → ${event.newValue}`);
});// Wichtig · Fallstricke
- Kein Ereignis im auslösenden Tab: Das Dokument, das
setItem()aufruft, erhält selbst keinstorage-Ereignis. Für Benachrichtigungen im selben Tab eigene Ereignisse oder einenBroadcastChannelverwenden. - Nur Strings:
newValueist immer ein String odernull. Zahlen oder Booleans kommen als"42"bzw."true"an. - Gleicher Wert: Wird ein Schlüssel auf denselben Wert gesetzt, wird in der Regel kein Ereignis ausgelöst.
- sessionStorage: Ereignisse werden nur zwischen Dokumenten derselben Sitzung (z. B. iframes im selben Tab) verteilt, nicht zwischen separaten Tabs.
- Sicherheit: Werte aus dem Speicher können von beliebigem Skript desselben Ursprungs gesetzt worden sein.
newValuenie ungeprüft ininnerHTMLeinsetzen (XSS-Gefahr) undJSON.parse()intry/catchkapseln. - Die Eigenschaft ist schreibgeschützt und wird in allen modernen Browsern unterstützt.