ServiceWorkerGlobalScope: backgroundfetchclick — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("backgroundfetchclick", handler)

Beschreibung

Das Ereignis backgroundfetchclick gehört zur Background Fetch API. Große Downloads wie Videos, Podcasts oder Offline-Pakete lassen sich damit über registration.backgroundFetch.fetch() an den Browser übergeben. Der Browser lädt sie dann auch weiter, wenn die Seite geschlossen ist, und zeigt dem Benutzer den Fortschritt in einer eigenen Oberfläche an, etwa als Benachrichtigung oder im Download-Bereich.

Klickt der Benutzer auf diese Anzeige, löst der Browser im Service Worker das Ereignis backgroundfetchclick aus. Der Handler erhält ein BackgroundFetchUpdateUIEvent (abgeleitet von BackgroundFetchEvent). Über dessen Eigenschaft registration kommt man an die zugehörige BackgroundFetchRegistration mit id, result, downloaded, downloadTotal usw.

Typischerweise öffnet man im Handler mit clients.openWindow() eine passende Seite, zum Beispiel eine Fortschrittsansicht, solange der Download läuft, oder die fertige Mediathek, sobald er abgeschlossen ist. Den Listener registriert man mit self.addEventListener("backgroundfetchclick", …) oder über die Eigenschaft self.onbackgroundfetchclick.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"backgroundfetchclick"`.
$handler Pflicht	(event: BackgroundFetchUpdateUIEvent) => void		Callback, der das Ereignis erhält. `event.registration` ist die betroffene `BackgroundFetchRegistration`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, wie bei `addEventListener` üblich.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Mit event.waitUntil(promise) hält man den Service Worker aktiv, bis asynchrone Arbeit wie clients.openWindow() erledigt ist.

Beispiele

Passende Seite beim Klick öffnen (addEventListener)

// sw.js
self.addEventListener("backgroundfetchclick", (event) => {
  const bgFetch = event.registration;

  // Fertig: Mediathek öffnen, sonst Fortschrittsseite
  const url = bgFetch.result === "success"
    ? "/mediathek"
    : `/downloads?id=${encodeURIComponent(bgFetch.id)}`;

  event.waitUntil(clients.openWindow(url));
});

Variante über die on-Eigenschaft

// sw.js
self.onbackgroundfetchclick = (event) => {
  const { id, downloaded, downloadTotal } = event.registration;
  const prozent = downloadTotal
    ? Math.round((downloaded / downloadTotal) * 100)
    : 0;
  console.log(`Klick auf Download ${id}: ${prozent} %`);
  event.waitUntil(clients.openWindow(`/downloads/${id}`));
};

Klick auf Download podcast-42: 37 %

Vorhandenes Fenster fokussieren statt neu öffnen

// sw.js
self.addEventListener("backgroundfetchclick", (event) => {
  event.waitUntil((async () => {
    const target = `/downloads/${event.registration.id}`;
    const fenster = await clients.matchAll({ type: "window", includeUncontrolled: true });
    const offen = fenster.find((c) => new URL(c.url).pathname === target);
    if (offen) {
      await offen.focus();
    } else {
      await clients.openWindow(target);
    }
  })());
});

Background Fetch auf der Seite starten (Voraussetzung)

// main.js – löst später ggf. backgroundfetchclick im SW aus
const reg = await navigator.serviceWorker.ready;
if ("backgroundFetch" in reg) {
  const bgFetch = await reg.backgroundFetch.fetch(
    "podcast-42",
    ["/audio/folge-42.mp3"],
    { title: "Folge 42 wird geladen", downloadTotal: 60 * 1024 * 1024 }
  );
  console.log("Gestartet:", bgFetch.id);
} else {
  console.log("Background Fetch wird nicht unterstützt");
}

Gestartet: podcast-42

// Wichtig · Fallstricke

Experimentell und eingeschränkt verfügbar: Das Ereignis gibt es nur in Chromium-basierten Browsern. Firefox und Safari unterstützen die Background Fetch API nicht. Prüfe deshalb vorher mit "backgroundFetch" in registration, ob die API vorhanden ist.
Das Ereignis wird nur im Service Worker ausgelöst, nicht im Fenster-Kontext. Es setzt einen sicheren Kontext (HTTPS) voraus.
clients.openWindow() ist nur als direkte Folge der Benutzerinteraktion erlaubt. Rufe es deshalb sofort im Handler innerhalb von event.waitUntil() auf und nicht erst nach langen asynchronen Umwegen.
Auf das Ereignis ist kein Verlass: Der Benutzer klickt vielleicht nie. Die Verarbeitung der geladenen Daten gehört deshalb in backgroundfetchsuccess bzw. backgroundfetchfail, nicht in diesen Handler.
Die Benutzeroberfläche und ihr Aussehen bestimmt allein der Browser. Mit updateUI() lässt sich die Anzeige nur in den Ereignissen backgroundfetchsuccess und backgroundfetchfail ändern, nicht in backgroundfetchclick.

Siehe auch

ServiceWorkerGlobalScope: backgroundfetchfail ServiceWorkerGlobalScope: backgroundfetchabort ServiceWorkerGlobalScope: backgroundfetchsuccess ServiceWorkerGlobalScope: contentdelete ServiceWorkerGlobalScope: cookiechange