Signatur
Beschreibung
Die schreibgeschützte Eigenschaft localStorage der Schnittstelle StorageAccessHandle liefert ein Storage-Objekt, das auf den nicht partitionierten lokalen Speicher des Ursprungs zugreift. Eingebettete Drittanbieter-Inhalte (z. B. ein <iframe> auf einer fremden Seite) sehen in modernen Browsern normalerweise nur einen partitionierten window.localStorage, der pro Top-Level-Site getrennt ist. Über diesen Handle kann das Iframe dagegen dieselben Daten lesen und schreiben wie beim direkten Besuch der eigenen Website.
Einen StorageAccessHandle erhält man als Auflösungswert von document.requestStorageAccess(types), wenn man dabei ein Objekt wie { localStorage: true } übergibt. Die Eigenschaft ist nur nutzbar, wenn genau dieser Speichertyp angefordert wurde; andernfalls löst der Zugriff eine Ausnahme aus.
Typische Einsatzfälle sind eingebettete Widgets (Kommentarsysteme, Chat, Single-Sign-on-Helfer), die Einstellungen oder Sitzungsdaten zwischen verschiedenen einbettenden Seiten teilen müssen, ohne auf Drittanbieter-Cookies angewiesen zu sein. Die API von Storage ist dieselbe wie gewohnt: getItem(), setItem(), removeItem(), clear() und length.
Rückgabewert
Storage-Objekt für den nicht partitionierten localStorage des aktuellen Ursprungs. Wirft einen SecurityError (DOMException), wenn localStorage beim Aufruf von requestStorageAccess() nicht angefordert bzw. nicht gewährt wurde.Beispiele
Nicht partitionierten localStorage im Iframe anfordern
// Im eingebetteten Iframe, ausgelöst durch eine Nutzeraktion
const button = document.querySelector('#login-sync');
button.addEventListener('click', async () => {
try {
const handle = await document.requestStorageAccess({ localStorage: true });
const store = handle.localStorage;
store.setItem('theme', 'dark');
console.log('Gespeichert:', store.getItem('theme'));
} catch (err) {
console.warn('Zugriff verweigert:', err.name);
}
});Partitionierten und nicht partitionierten Speicher vergleichen
const compareStorage = async () => {
// Partitionierter Speicher (nur für diese Top-Level-Site)
window.localStorage.setItem('scope', 'partitioniert');
const handle = await document.requestStorageAccess({ localStorage: true });
// Nicht partitionierter Speicher (wie bei direktem Besuch)
handle.localStorage.setItem('scope', 'global');
console.log(window.localStorage.getItem('scope'));
console.log(handle.localStorage.getItem('scope'));
};
document.querySelector('#compare').addEventListener('click', compareStorage);Fallback mit Feature-Erkennung und Fehlerbehandlung
const getSharedStorage = async () => {
if (!('requestStorageAccess' in document)) return window.localStorage;
try {
const handle = await document.requestStorageAccess({ localStorage: true });
return handle.localStorage;
} catch (err) {
// NotAllowedError: Zugriff verweigert
// SecurityError: localStorage nicht im Handle enthalten
console.warn(`Fallback wegen ${err.name}`);
return window.localStorage;
}
};
document.querySelector('#save').addEventListener('click', async () => {
const storage = await getSharedStorage();
storage.setItem('lastVisit', new Date().toISOString());
console.log('Einträge:', storage.length);
});// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Erweiterung der Storage Access API auf Nicht-Cookie-Speicher (
StorageAccessHandle) wird derzeit nur von Chromium-Browsern (ab Version 125) unterstützt. Firefox und Safari kennen zwardocument.requestStorageAccess(), aber ohne Parameter und ohne Handle. Deshalb immer eine Feature-Erkennung und einen Fallback einbauen. - Nur bei Anforderung verfügbar: Wird
requestStorageAccess()ohne{ localStorage: true }aufgerufen (etwa nur mit{ sessionStorage: true }), wirft der Zugriff aufhandle.localStorageeinenSecurityError. - Nutzeraktion erforderlich:
requestStorageAccess()muss in der Regel durch eine Nutzeraktion (z. B. Klick) ausgelöst werden. Ohne diese wird das Promise mitNotAllowedErrorabgelehnt. - Nicht mit
window.localStorageverwechseln: Das globalelocalStorageim Iframe bleibt auch nach gewährtem Zugriff partitioniert. Nur das über den Handle erhaltene Objekt greift auf den gemeinsamen Speicher zu. - Datenschutz: Nicht partitionierter Speicher ermöglicht seitenübergreifendes Wiedererkennen. Speichere nur Daten, die für die Funktion wirklich nötig sind, und nie sensible Daten im Klartext, denn localStorage ist für jedes Skript desselben Ursprungs lesbar (XSS-Risiko).
storage-Event: Änderungen über den Handle lösenstorage-Events in anderen nicht partitionierten Kontexten desselben Ursprungs aus, nicht aber im partitionierten Speicher.