StorageAccessHandle.caches — Eigenschaft · JavaScript-Referenz

Signatur

get StorageAccessHandle.caches

Beschreibung

Die schreibgeschützte Eigenschaft caches des Interfaces StorageAccessHandle liefert ein CacheStorage-Objekt. Anders als das globale window.caches ist es nicht nach dem Top-Level-Kontext partitioniert. Ein eingebettetes Drittanbieter-iframe sieht darüber also dieselben Caches, die es auch als eigene Hauptseite (First Party) nutzt.

Einen StorageAccessHandle bekommt man aus document.requestStorageAccess(types), wenn man dort ein Objekt mit gewünschten Speicherarten übergibt, z. B. { caches: true }. Die Eigenschaft ist nur dann nutzbar, wenn caches dabei ausdrücklich angefordert wurde. Sonst wirft der Zugriff eine SecurityError-DOMException.

Typische Einsätze sind eingebettete Widgets, Anmeldedienste oder Medienplayer auf fremden Seiten. Sie wollen Ressourcen, die sie in ihrem eigenen First-Party-Kontext zwischengespeichert haben (z. B. Assets oder API-Antworten), wiederverwenden, statt in jeder Partition einen neuen Cache aufzubauen.

Das zurückgegebene Objekt hat dieselbe Schnittstelle wie das normale CacheStorage: open(), match(), has(), keys() und delete(). Alle Methoden arbeiten asynchron und liefern Promises.

Rückgabewert

Typ

CacheStorage

Beschreibung

Ein unpartitioniertes CacheStorage-Objekt. Wirft eine SecurityError-DOMException, wenn caches in requestStorageAccess() nicht angefordert oder nicht gewährt wurde.

Beispiele

Unpartitionierten Cache anfordern und öffnen

// Läuft in einem Drittanbieter-iframe, ausgelöst durch eine Nutzeraktion
document.querySelector('#login').addEventListener('click', async () => {
  try {
    const handle = await document.requestStorageAccess({ caches: true });
    const cache = await handle.caches.open('widget-assets-v1');
    const treffer = await cache.match('/widget/config.json');
    console.log(treffer ? 'Konfiguration aus First-Party-Cache' : 'Nicht im Cache');
  } catch (err) {
    console.error('Speicherzugriff verweigert:', err.name);
  }
});

Konfiguration aus First-Party-Cache

Cache-first-Abruf mit Fallback auf das Netzwerk

const ladeMitCache = async (cacheStorage, url) => {
  const cache = await cacheStorage.open('api-v1');
  const vorhanden = await cache.match(url);
  if (vorhanden) return vorhanden.json();

  const antwort = await fetch(url);
  if (antwort.ok) await cache.put(url, antwort.clone());
  return antwort.json();
};

const handle = await document.requestStorageAccess({ caches: true });
const daten = await ladeMitCache(handle.caches, '/api/profil');
console.log(daten.name);

Max Mustermann

SecurityError, wenn caches nicht angefordert wurde

const handle = await document.requestStorageAccess({ localStorage: true });

try {
  const namen = await handle.caches.keys();
  console.log(namen);
} catch (err) {
  // Zugriff auf handle.caches wirft sofort
  console.log(err instanceof DOMException, err.name);
}

true SecurityError

Feature-Erkennung mit Rückfall auf den partitionierten Cache

const holeCacheStorage = async () => {
  if (typeof document.requestStorageAccess === 'function') {
    try {
      const handle = await document.requestStorageAccess({ caches: true });
      if (handle && 'caches' in handle) return handle.caches;
    } catch {
      // verweigert oder Signatur nicht unterstützt
    }
  }
  return window.caches; // partitioniert
};

const storage = await holeCacheStorage();
console.log(await storage.keys());

["widget-assets-v1", "api-v1"]

// Wichtig · Fallstricke

Browser-Unterstützung: Die erweiterte Storage Access API mit StorageAccessHandle gibt es bisher nur in Chromium-Browsern (Chrome/Edge ab 125). Firefox und Safari unterstützen nur document.requestStorageAccess() ohne Argument. Das gibt dort nur Cookie-Zugriff frei und liefert keinen Handle. Deshalb vorher per Feature-Erkennung prüfen.
Explizit anfordern: Ohne { caches: true } (oder { all: true }) im Aufruf wirft schon das Lesen von handle.caches eine SecurityError-Ausnahme, nicht erst die spätere Methode.
Nutzeraktion nötig: requestStorageAccess() braucht in der Regel eine vorübergehende Nutzeraktivierung, etwa einen Klick. Eine vorher erteilte Berechtigung kann über navigator.permissions.query({ name: 'storage-access' }) abgefragt werden.
Nicht mit window.caches verwechseln: Das globale caches im iframe bleibt partitioniert. Nur über den Handle erreicht man den First-Party-Speicher.
Sicherheit und Datenschutz: Der unpartitionierte Cache ist für Websites gemeinsam erreichbar. Keine sensiblen, nutzerspezifischen Antworten ohne Grund dort ablegen, und die Herkunft (Origin) der Einbettung per Permissions-Policy bzw. CSP frame-ancestors einschränken.
Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

Window.caches StorageAccessHandle.locks StorageAccessHandle.indexedDB StorageAccessHandle.localStorage StorageAccessHandle.sessionStorage