StorageManager.persist() — Methode · JavaScript-Referenz

Signatur

StorageManager.prototype.persist()

Beschreibung

Standardmäßig gilt der Speicher einer Website (IndexedDB, Cache Storage, OPFS, localStorage usw.) als „best-effort“. Wird der Speicherplatz knapp, darf der Browser diese Daten ohne Rückfrage löschen. Mit navigator.storage.persist() fordert eine Anwendung an, dass ihr Speicher-Bucket in den Modus „persistent“ wechselt. Danach entfernt der Browser die Daten nur noch, wenn die Person sie selbst löscht, zum Beispiel über die Browser-Einstellungen.

Das ist wichtig für Offline-fähige Web-Apps und PWAs, für lokale Entwürfe, heruntergeladene Medien und alle Daten, die nicht (oder noch nicht) auf einem Server gesichert sind. Rufe die Methode am besten auf, wenn die Person etwas Wichtiges tut, etwa ein Dokument offline speichert oder die App installiert. Ein Aufruf direkt beim Laden der Seite ist weniger sinnvoll.

Wie der Browser entscheidet, ist unterschiedlich: Firefox fragt die Person über einen Berechtigungsdialog. Chromium-Browser entscheiden ohne Dialog nach Kriterien wie Lesezeichen, Nutzungsintensität, installierter PWA oder erteilter Benachrichtigungs-Berechtigung. Safari nutzt ebenfalls eigene Heuristiken. Das Ergebnis ist also nicht garantiert. Plane immer auch den Fall ein, dass die Anfrage abgelehnt wird.

Ob der Speicher bereits persistent ist, lässt sich ohne Nebenwirkungen mit navigator.storage.persisted() prüfen. Wie viel Platz belegt und verfügbar ist, liefert navigator.storage.estimate().

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Löst mit true auf, wenn die Berechtigung erteilt wurde und der Bucket jetzt persistent ist. Andernfalls löst es mit false auf. Das Promise wird abgelehnt (TypeError), wenn der Speicher-Manager nicht verfügbar ist, etwa in einem undurchsichtigen Ursprung wie einem sandbox-iframe.

Beispiele

Persistenten Speicher anfordern mit Feature-Erkennung

const requestPersistence = async () => {
  if (!navigator.storage?.persist) {
    console.log('StorageManager.persist() wird nicht unterstützt');
    return false;
  }
  const granted = await navigator.storage.persist();
  console.log(granted
    ? 'Speicher ist jetzt persistent.'
    : 'Speicher bleibt „best-effort“ und kann gelöscht werden.');
  return granted;
};

requestPersistence();

Speicher ist jetzt persistent.

Erst prüfen, dann nur bei Bedarf anfordern

const ensurePersistentStorage = async () => {
  // persisted() hat keine Nebenwirkungen und zeigt keinen Dialog
  if (await navigator.storage.persisted()) {
    return 'bereits persistent';
  }
  const granted = await navigator.storage.persist();
  return granted ? 'neu erteilt' : 'abgelehnt';
};

ensurePersistentStorage().then((status) => console.log(`Status: ${status}`));

Status: bereits persistent

Beim Offline-Speichern eines Dokuments anfordern (mit Kontingent-Info)

const saveOfflineButton = document.querySelector('#save-offline');

saveOfflineButton.addEventListener('click', async () => {
  // Anfrage im Zusammenhang mit einer Nutzeraktion stellen
  const granted = await navigator.storage.persist();
  const { usage, quota } = await navigator.storage.estimate();
  const usedMB = (usage / 1024 / 1024).toFixed(1);
  const quotaMB = (quota / 1024 / 1024).toFixed(0);

  console.log(`Persistent: ${granted}, belegt: ${usedMB} MB von ${quotaMB} MB`);

  if (!granted) {
    alert('Hinweis: Offline-Daten können bei Speichermangel vom Browser gelöscht werden.');
  }
});

Persistent: true, belegt: 12.4 MB von 2048 MB

// Wichtig · Fallstricke

Kein garantiertes Ergebnis: In Chromium wird false oft ohne Dialog zurückgegeben, wenn die Seite die Kriterien nicht erfüllt, zum Beispiel wenig genutzt, nicht installiert oder ohne Lesezeichen. Wiederholte Aufrufe ändern daran nichts. Die App muss auch ohne persistenten Speicher funktionieren.
Nur in sicheren Kontexten: Die Methode steht nur unter HTTPS oder localhost zur Verfügung. In Workern ist persist() nicht verfügbar, dort gibt es nur persisted() und estimate().
Firefox-Dialog: Firefox zeigt einen Berechtigungsdialog. Rufe die Methode deshalb im Zusammenhang mit einer Nutzeraktion auf, damit der Dialog nachvollziehbar ist und nicht als lästig abgelehnt wird.
Persistent heißt nicht unverlierbar: Personen können die Daten jederzeit manuell löschen, im privaten Modus gehen sie beim Schließen verloren, und das Kontingent (estimate().quota) gilt weiterhin. Wichtige Daten sollten zusätzlich auf einem Server gesichert werden.
Safari: Ohne persistenten Speicher löscht Safari (ITP) Skript-beschriebenen Speicher nach 7 Tagen ohne Interaktion. Bei installierten Home-Screen-Web-Apps gilt diese Regel nicht.
Die Persistenz gilt für den gesamten Standard-Bucket des Ursprungs, also für alle Speicherarten gemeinsam.

Siehe auch

StorageManager StorageManager.persisted() StorageManager.estimate() StorageManager.getDirectory() Navigator.storage CacheStorage