new BackgroundFetchEvent() — Methode · JavaScript-Referenz

Signatur

new BackgroundFetchEvent(type, options)

Beschreibung

Der Konstruktor BackgroundFetchEvent() erzeugt ein Event-Objekt der Background Fetch API. Solche Events bekommt ein Service Worker, sobald ein Hintergrund-Download einen neuen Zustand erreicht, zum Beispiel backgroundfetchabort oder backgroundfetchclick. Über die Eigenschaft registration hat das Event Zugriff auf die zugehörige BackgroundFetchRegistration.

Normalerweise erzeugt der Browser diese Events selbst. Den Konstruktor ruft man nur selten direkt auf. Sinnvoll ist das vor allem in Tests, wenn man Event-Handler eines Service Workers mit einem nachgebauten Event auslösen will, oder beim Schreiben von Polyfills und Mocks.

BackgroundFetchEvent erbt von ExtendableEvent. Deshalb steht auch waitUntil() zur Verfügung, mit dem der Service Worker so lange aktiv bleibt, bis eine asynchrone Aufgabe erledigt ist. Für die Events backgroundfetchsuccess und backgroundfetchfail gibt es die Unterklasse BackgroundFetchUpdateUIEvent, die zusätzlich updateUI() anbietet.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Events, z. B. `"backgroundfetchabort"` oder `"backgroundfetchclick"`. Groß- und Kleinschreibung zählt.
$options Pflicht	Object	Einstellungsobjekt. Es enthält alle Optionen von `ExtendableEventInit` (`bubbles`, `cancelable`, `composed`) und zusätzlich `registration`.
$options.registration Pflicht	BackgroundFetchRegistration	Die `BackgroundFetchRegistration`, zu der das Event gehört. Fehlt sie, wirft der Konstruktor einen `TypeError`.

Rückgabewert

Typ

BackgroundFetchEvent

Beschreibung

Ein neues BackgroundFetchEvent-Objekt. Seine Eigenschaft registration verweist auf die übergebene Registrierung.

Beispiele

Browser-Events im Service Worker verarbeiten (üblicher Fall)

// sw.js – der Browser erzeugt die BackgroundFetchEvent-Objekte selbst
self.addEventListener('backgroundfetchabort', (event) => {
  const { id } = event.registration;
  console.log(`Download ${id} wurde abgebrochen`);

  // Service Worker aktiv halten, bis aufgeräumt ist
  event.waitUntil(caches.delete(`bgfetch-${id}`));
});

self.addEventListener('backgroundfetchclick', (event) => {
  // Nutzer hat auf die Download-Anzeige des Browsers geklickt
  event.waitUntil(clients.openWindow(`/downloads/${event.registration.id}`));
});

Download podcast-42 wurde abgebrochen

Event von Hand erzeugen und auslösen (z. B. im Test)

// sw.js – eine laufende Registrierung holen und ein nachgebautes Event auslösen
const simulateAbort = async (id) => {
  const registration = await self.registration.backgroundFetch.get(id);
  if (!registration) {
    console.warn(`Keine Registrierung mit der ID ${id}`);
    return;
  }

  const event = new BackgroundFetchEvent('backgroundfetchabort', {
    registration
  });

  console.log(event.type, event.registration.id);
  self.dispatchEvent(event);
};

simulateAbort('podcast-42');

backgroundfetchabort podcast-42

Fehlende Unterstützung und fehlende Pflicht-Option abfangen

// Vorher prüfen, ob die API überhaupt vorhanden ist
if (typeof BackgroundFetchEvent === 'undefined') {
  console.log('Background Fetch wird hier nicht unterstützt');
} else {
  try {
    // Ohne registration wirft der Konstruktor einen Fehler
    new BackgroundFetchEvent('backgroundfetchclick', {});
  } catch (err) {
    console.log(err.name);
  }
}

TypeError

// Wichtig · Fallstricke

Experimentell: Die Background Fetch API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man prüfen, ob sie vorhanden ist, z. B. mit 'BackgroundFetchManager' in self.
Nur im Service Worker: Der Konstruktor steht ausschließlich im ServiceWorkerGlobalScope bereit. Im Hauptthread (window) ist BackgroundFetchEvent nicht definiert.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder auf localhost.
Pflicht-Option registration: Ohne diese Option wirft der Konstruktor einen TypeError. Ein eigenes BackgroundFetchRegistration-Objekt kann man nicht erzeugen. Man bekommt es nur über backgroundFetch.fetch() oder backgroundFetch.get().
waitUntil() bei selbst erzeugten Events: Ruft man waitUntil() bei einem von Hand ausgelösten Event auf, verlängert das die Lebensdauer des Service Workers nicht. In der Regel wird dabei sogar ein InvalidStateError geworfen, weil das Event nicht vom Browser stammt.
Für backgroundfetchsuccess und backgroundfetchfail sollte man BackgroundFetchUpdateUIEvent nutzen, weil nur diese Klasse updateUI() hat.

Siehe auch

BackgroundFetchEvent BackgroundFetchEvent.registration BackgroundFetchUpdateUIEvent BackgroundFetchRegistration BackgroundFetchManager ExtendableEvent ExtendableEvent.waitUntil()