BackgroundFetchEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface BackgroundFetchEvent extends ExtendableEvent

Beschreibung

Das Interface BackgroundFetchEvent gehört zur Background Fetch API und steht für Ereignisse, die der Browser im ServiceWorkerGlobalScope auslöst. Mit einem Background Fetch lädt der Browser große Ressourcen wie Filme, Podcasts oder Offline-Pakete herunter. Das funktioniert auch dann weiter, wenn der Nutzer den Tab oder sogar den Browser schließt. Der Browser zeigt dabei eine eigene Fortschrittsanzeige an.

BackgroundFetchEvent erbt von ExtendableEvent. Deshalb gibt es die Methode waitUntil(): Mit ihr hältst du den Service Worker am Leben, bis ein Promise erledigt ist, etwa beim Aufräumen des Caches. Die einzige eigene Eigenschaft ist registration. Sie enthält die zugehörige BackgroundFetchRegistration mit ID, Fortschritt und Status.

Direkt als BackgroundFetchEvent kommen diese Ereignisse an:

backgroundfetchabort: Der Nutzer oder die Anwendung hat den Download abgebrochen.
backgroundfetchclick: Der Nutzer hat auf die Download-Anzeige des Browsers geklickt.

Die Ereignisse backgroundfetchsuccess und backgroundfetchfail verwenden die Unterklasse BackgroundFetchUpdateUIEvent. Sie bietet zusätzlich updateUI(). Du registrierst die Handler per self.addEventListener('backgroundfetchclick', …) oder über die On-Eigenschaften wie self.onbackgroundfetchabort.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Ereignisses, z. B. `"backgroundfetchabort"` oder `"backgroundfetchclick"` (nur für den Konstruktor).
$options Pflicht	object	Initialisierungsobjekt. Es erweitert `ExtendableEventInit` und muss die Eigenschaft `registration` (`BackgroundFetchRegistration`) enthalten.
$options.registration Pflicht	BackgroundFetchRegistration	Die Registrierung, auf die sich das Ereignis bezieht. Später abrufbar über `event.registration`.

Rückgabewert

Typ

BackgroundFetchEvent

Beschreibung

Der Konstruktor new BackgroundFetchEvent(type, options) liefert ein neues Ereignisobjekt. In der Praxis erzeugt aber der Browser die Instanzen und übergibt sie an deine Handler im Service Worker.

Beispiele

Background Fetch auf der Seite starten (Vorbereitung)

// main.js – im Fenster-Kontext
const startDownload = async () => {
  const reg = await navigator.serviceWorker.ready;
  if (!('backgroundFetch' in reg)) {
    console.log('Background Fetch wird nicht unterstützt');
    return;
  }
  const bgFetch = await reg.backgroundFetch.fetch(
    'episode-42',
    ['/media/episode-42.mp3'],
    { title: 'Podcast Folge 42', downloadTotal: 60 * 1024 * 1024 }
  );
  console.log('Gestartet:', bgFetch.id);
};

startDownload();

Gestartet: episode-42

Klick auf die Download-Anzeige behandeln (addEventListener)

// sw.js – im Service Worker
self.addEventListener('backgroundfetchclick', (event) => {
  const { id, result } = event.registration;
  const url = result === 'success'
    ? `/player?episode=${encodeURIComponent(id)}`
    : '/downloads';

  // Service Worker aktiv halten, bis das Fenster geöffnet ist
  event.waitUntil(clients.openWindow(url));
});

Abbruch behandeln und Cache aufräumen (on-Eigenschaft)

// sw.js – im Service Worker
self.onbackgroundfetchabort = (event) => {
  const { id, downloaded, downloadTotal } = event.registration;
  console.log(`Abgebrochen: ${id} (${downloaded}/${downloadTotal} Bytes)`);

  event.waitUntil(
    caches.delete(`bgfetch-${id}`)
  );
};

Abgebrochen: episode-42 (15728640/62914560 Bytes)

Ereignis manuell erzeugen (z. B. für Tests)

// sw.js – registration stammt aus einem bestehenden Background Fetch
const testAbort = async () => {
  const bgReg = await self.registration.backgroundFetch.get('episode-42');
  if (!bgReg) return;
  const evt = new BackgroundFetchEvent('backgroundfetchabort', {
    registration: bgReg
  });
  console.log(evt.type, evt.registration.id);
};

testAbort();

backgroundfetchabort episode-42

// Wichtig · Fallstricke

Experimentell und nur in Chromium verfügbar: Chrome, Edge und Opera unterstützen die API, Firefox und Safari nicht. Prüfe die Unterstützung immer mit 'backgroundFetch' in registration und plane eine Alternative ein, z. B. einen normalen fetch().
Die API steht nur in sicheren Kontexten (HTTPS) und nur mit einem aktiven Service Worker zur Verfügung.
backgroundfetchsuccess und backgroundfetchfail liefern ein BackgroundFetchUpdateUIEvent. Nur dort gibt es updateUI(). Wenn du updateUI() in einem backgroundfetchclick- oder backgroundfetchabort-Handler aufrufst, schlägt das fehl.
Rufe event.waitUntil() synchron im Handler auf. Sonst kann der Browser den Service Worker beenden, bevor die asynchrone Arbeit fertig ist.
clients.openWindow() funktioniert im Service Worker nur als Reaktion auf eine Nutzeraktion. Bei backgroundfetchclick ist diese Bedingung erfüllt, bei backgroundfetchabort nicht.
Die heruntergeladenen Daten werden nicht automatisch im Cache gespeichert. Das musst du im backgroundfetchsuccess-Handler selbst über registration.matchAll() erledigen.

Siehe auch

BackgroundFetchRecord BackgroundFetchManager BackgroundFetchUpdateUIEvent BackgroundFetchRegistration FetchEvent