BackgroundFetchManager.get() — Methode · JavaScript-Referenz

Signatur

BackgroundFetchManager.prototype.get(id)

Beschreibung

Mit get() holen Sie eine laufende Hintergrund-Übertragung (Background Fetch) wieder ab, die zuvor mit BackgroundFetchManager.fetch() unter einer bestimmten id gestartet wurde. Erreichbar ist die Methode über registration.backgroundFetch eines ServiceWorkerRegistration-Objekts, und zwar sowohl im Fensterkontext als auch im Service Worker selbst.

Typische Anwendungsfälle sind:

Nach einem Neuladen der Seite den Fortschritt eines großen Downloads (z. B. Podcast-Folge, Film, Offline-Paket) wieder in der Oberfläche anzeigen.
Vor dem Start prüfen, ob ein Download mit derselben id schon läuft, damit fetch() nicht mit einem TypeError abbricht.
Eine laufende Übertragung gezielt über registration.abort() abbrechen.

Das Promise wird nur mit aktiven Registrierungen aufgelöst. Ist der Fetch schon abgeschlossen und das zugehörige Ereignis (backgroundfetchsuccess, backgroundfetchfail, backgroundfetchabort) im Service Worker vollständig verarbeitet, liefert get() undefined.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die Kennung der Hintergrund-Übertragung, die beim Aufruf von `BackgroundFetchManager.fetch(id, requests, options)` vergeben wurde.

Rückgabewert

Typ

Promise<BackgroundFetchRegistration | undefined>

Beschreibung

Ein Promise, das mit der passenden BackgroundFetchRegistration aufgelöst wird oder mit undefined, wenn keine aktive Registrierung mit dieser id existiert.

Beispiele

Laufenden Download abfragen und Fortschritt anzeigen

const zeigeFortschritt = async (id) => {
  const reg = await navigator.serviceWorker.ready;
  const bgFetch = await reg.backgroundFetch.get(id);

  if (!bgFetch) {
    console.log(`Kein aktiver Download mit der ID "${id}".`);
    return;
  }

  const aktualisieren = () => {
    const prozent = bgFetch.downloadTotal
      ? Math.round((bgFetch.downloaded / bgFetch.downloadTotal) * 100)
      : 0;
    console.log(`${id}: ${prozent} %`);
  };

  aktualisieren();
  bgFetch.addEventListener('progress', aktualisieren);
};

zeigeFortschritt('podcast-folge-42');

podcast-folge-42: 37 %

Doppelten Start verhindern

const starteDownload = async (id, urls) => {
  const reg = await navigator.serviceWorker.ready;

  if (!('backgroundFetch' in reg)) {
    throw new Error('Background Fetch wird nicht unterstützt.');
  }

  // Existiert schon eine aktive Registrierung, diese wiederverwenden
  const vorhanden = await reg.backgroundFetch.get(id);
  if (vorhanden) return vorhanden;

  return reg.backgroundFetch.fetch(id, urls, {
    title: 'Offline-Paket',
    downloadTotal: 50 * 1024 * 1024
  });
};

starteDownload('offline-paket', ['/pakete/karten.zip'])
  .then((bg) => console.log('Aktiv:', bg.id));

Aktiv: offline-paket

Download gezielt abbrechen

const brecheAb = async (id) => {
  const reg = await navigator.serviceWorker.ready;
  const bgFetch = await reg.backgroundFetch.get(id);
  if (!bgFetch) return false;
  return bgFetch.abort();
};

document.querySelector('#abbrechen')
  .addEventListener('click', async () => {
    const ok = await brecheAb('film-4k');
    console.log(ok ? 'Abgebrochen' : 'Nichts zum Abbrechen');
  });

Abgebrochen

// Wichtig · Fallstricke

Kompatibilität: Experimentelle API, derzeit nur in Chromium-Browsern (Chrome, Edge, Opera) verfügbar. Firefox und Safari unterstützen sie nicht. Prüfen Sie die Verfügbarkeit daher immer mit 'backgroundFetch' in registration.
Die API steht nur in sicheren Kontexten (HTTPS oder localhost) und mit einem aktiven Service Worker zur Verfügung. navigator.serviceWorker.ready wird erst aufgelöst, wenn ein Service Worker aktiv ist.
Die Rückgabe undefined bedeutet nicht unbedingt, dass es nie einen Download gab. Er kann auch schon abgeschlossen oder abgebrochen und fertig verarbeitet sein. Den Endzustand sollten Sie deshalb im Service Worker über die backgroundfetch*-Ereignisse speichern, etwa in IndexedDB oder in der Cache API.
Jeder Aufruf von get() kann ein neues BackgroundFetchRegistration-Objekt liefern. Vergleichen Sie Registrierungen daher über id und nicht mit ===.
Die Registrierungen gelten nur für die jeweilige Service-Worker-Registrierung (Scope). Ein anderer Scope sieht dieselbe id nicht.

Siehe auch

NavigationPreloadManager.getState() new TaskPriorityChangeEvent() BackgroundFetchManager.fetch() BackgroundFetchManager.getIds() new BackgroundFetchEvent()