StorageAccessHandle.estimate() — Methode · JavaScript-Referenz

Signatur

StorageAccessHandle.prototype.estimate()

Beschreibung

estimate() ist eine Methode des StorageAccessHandle. Dieses Objekt erhält man, wenn man document.requestStorageAccess() mit einem Optionsobjekt aufruft, zum Beispiel { estimate: true }. Die Methode arbeitet wie navigator.storage.estimate(). Sie bezieht sich aber auf den unpartitionierten Speicher, also auf den Speicher, den die Origin auch als Hauptseite (First-Party) nutzt. Der partitionierte Speicher des aktuellen eingebetteten Kontexts ist nicht gemeint.

Brauchbar ist das vor allem in eingebetteten Drittanbieter-Inhalten in einem <iframe>, etwa Bezahl-Widgets, Kommentarsysteme oder Single-Sign-On-Lösungen. Durch die Speicherpartitionierung sehen diese standardmäßig nur einen getrennten Speicherbereich. Haben sie den Zugriff über die Storage Access API erhalten, können sie mit estimate() prüfen, wie viel Platz im gemeinsamen First-Party-Speicher belegt ist und wie viel noch frei ist. Das ist nützlich, bevor man z. B. größere Datenmengen in IndexedDB oder in der Cache API ablegt.

Die Methode steht nur zur Verfügung, wenn bei requestStorageAccess() die Option estimate: true (oder all: true) gesetzt war. Wie beim Original sind die zurückgegebenen Werte Schätzungen. Browser runden sie oder verfälschen sie absichtlich leicht, damit sie sich nicht zum Fingerprinting eignen.

Rückgabewert

Typ

Promise<StorageEstimate>

Beschreibung

Ein Promise, das sich mit einem StorageEstimate-Objekt erfüllt. Die Eigenschaften: usage (belegte Bytes) und quota (verfügbares Kontingent in Bytes). In Chromium kommt zusätzlich usageDetails hinzu, eine nicht standardisierte Aufschlüsselung nach Speichertyp. Das Promise wird abgelehnt, wenn der Zugriff nicht gewährt wurde oder die Option estimate fehlte.

Beispiele

Unpartitionierten Speicherverbrauch im iframe abfragen

// Läuft in einem eingebetteten Drittanbieter-iframe
const button = document.querySelector('#speicher-pruefen');

button.addEventListener('click', async () => {
  try {
    // Muss durch eine Nutzeraktion ausgelöst werden
    const handle = await document.requestStorageAccess({ estimate: true });
    const { usage, quota } = await handle.estimate();
    const mb = (bytes) => (bytes / 1024 / 1024).toFixed(1);
    console.log(`Belegt: ${mb(usage)} MB von ${mb(quota)} MB`);
  } catch (err) {
    console.warn('Speicherzugriff verweigert:', err.name);
  }
});

Belegt: 12.4 MB von 2048.0 MB

Vor großem Download freien Platz prüfen

const hatGenugPlatz = async (handle, benoetigteBytes) => {
  const { usage, quota } = await handle.estimate();
  return quota - usage >= benoetigteBytes;
};

document.querySelector('#offline').addEventListener('click', async () => {
  const handle = await document.requestStorageAccess({
    estimate: true,
    indexedDB: true
  });

  if (await hatGenugPlatz(handle, 50 * 1024 * 1024)) {
    const db = handle.indexedDB.open('offline-daten', 1);
    db.onsuccess = () => console.log('Unpartitionierte DB geöffnet');
  } else {
    console.log('Zu wenig Speicher für Offline-Paket');
  }
});

Unpartitionierte DB geöffnet

Partitioniert vs. unpartitioniert vergleichen

document.querySelector('#vergleich').addEventListener('click', async () => {
  const partitioniert = await navigator.storage.estimate();
  const handle = await document.requestStorageAccess({ estimate: true });
  const unpartitioniert = await handle.estimate();

  console.table({
    partitioniert: partitioniert.usage,
    unpartitioniert: unpartitioniert.usage
  });
});

Tabelle mit zwei unterschiedlichen usage-Werten

// Wichtig · Fallstricke

Option erforderlich: Wird requestStorageAccess() ohne estimate: true bzw. all: true aufgerufen, ist estimate() auf dem Handle nicht nutzbar. Der Aufruf löst dann einen SecurityError (DOMException) aus.
Nutzeraktion: requestStorageAccess() braucht in der Regel eine Nutzeraktion wie einen Klick. Außerdem kann der Browser eine Berechtigungsabfrage anzeigen. Ruft man die Methode ohne Nutzeraktion auf, wird das Promise meist abgelehnt.
Nur Schätzwerte: usage und quota sind ungenau und aus Datenschutzgründen oft gerundet. Verlassen Sie sich nicht auf exakte Byte-Werte.
Kompatibilität: Das erweiterte Optionsobjekt für requestStorageAccess() und damit auch StorageAccessHandle gibt es bisher nur in Chromium-Browsern (ab Version 125). Firefox und Safari unterstützen nur die einfache Form ohne Handle. Prüfen Sie vorher, ob die Funktion vorhanden ist, z. B. mit typeof handle?.estimate === 'function'.
Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

new SpeechSynthesisUtterance() StorageAccessHandle.BroadcastChannel() StorageAccessHandle.getDirectory() StorageAccessHandle.SharedWorker() StorageAccessHandle.createObjectURL()