ServiceWorkerGlobalScope: backgroundfetchabort — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("backgroundfetchabort", handler)

Beschreibung

Das Ereignis backgroundfetchabort wird im ServiceWorkerGlobalScope ausgelöst, wenn eine mit BackgroundFetchManager.fetch() gestartete Hintergrund-Übertragung abgebrochen wird. Das passiert zum Beispiel, wenn der Benutzer den Download in der Download-Benachrichtigung des Browsers abbricht oder die Anwendung selbst BackgroundFetchRegistration.abort() aufruft.

Der Handler bekommt ein BackgroundFetchEvent (ein Untertyp von ExtendableEvent). Über event.registration kommt man an die betroffene BackgroundFetchRegistration mit id, downloaded, downloadTotal und failureReason (hier "aborted"). Typische Aufgaben sind: bereits geladene Teildaten verwerfen, Metadaten in IndexedDB bereinigen, offene Clients informieren oder den Abbruch protokollieren.

Registriert wird der Handler entweder mit self.addEventListener("backgroundfetchabort", handler) oder über die Eigenschaft self.onbackgroundfetchabort = handler. Asynchrone Aufräumarbeiten sollten in event.waitUntil() gekapselt werden, damit der Browser den Service Worker nicht vorzeitig beendet.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"backgroundfetchabort"`.
$handler Pflicht	(event: BackgroundFetchEvent) => void		Callback, das ein `BackgroundFetchEvent` mit der Eigenschaft `registration` und der Methode `waitUntil()` erhält.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein BackgroundFetchEvent.

Beispiele

Abbruch protokollieren und Teildaten aufräumen (addEventListener)

// sw.js
self.addEventListener("backgroundfetchabort", (event) => {
  const reg = event.registration;
  console.log(`Background Fetch "${reg.id}" abgebrochen`, reg.failureReason);

  // Aufräumen in waitUntil kapseln
  event.waitUntil(
    caches.delete(`bgfetch-${reg.id}`)
  );
});

Background Fetch "podcast-42" abgebrochen aborted

Offene Tabs über den Abbruch informieren (on-Property)

// sw.js
self.onbackgroundfetchabort = (event) => {
  event.waitUntil((async () => {
    const clients = await self.clients.matchAll({ includeUncontrolled: true });
    for (const client of clients) {
      client.postMessage({
        type: "download-aborted",
        id: event.registration.id,
        downloaded: event.registration.downloaded
      });
    }
  })());
};

Background Fetch starten und aus der Seite abbrechen

// main.js (Seite)
const reg = await navigator.serviceWorker.ready;

if ("backgroundFetch" in reg) {
  const bgFetch = await reg.backgroundFetch.fetch(
    "podcast-42",
    ["/media/episode-42.mp3"],
    { title: "Episode 42", downloadTotal: 60 * 1024 * 1024 }
  );

  document.querySelector("#cancel").addEventListener("click", async () => {
    const ok = await bgFetch.abort(); // löst backgroundfetchabort im SW aus
    console.log("Abgebrochen:", ok);
  });
} else {
  console.log("Background Fetch wird nicht unterstützt");
}

Abgebrochen: true

Listener wieder entfernen

// sw.js
const onAbort = (event) => {
  console.log("Abbruch:", event.registration.id);
};

self.addEventListener("backgroundfetchabort", onAbort);
// später, z. B. nach Konfigurationswechsel:
self.removeEventListener("backgroundfetchabort", onAbort);

// Wichtig · Fallstricke

Experimentell und eingeschränkt verfügbar: Die Background Fetch API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet), und zwar nur in sicheren Kontexten (HTTPS). Firefox und Safari unterstützen sie nicht. Vor der Nutzung mit "backgroundFetch" in registration prüfen.
Das Ereignis wird nur im Service Worker ausgelöst, nicht im window. Die Seite erfährt vom Abbruch über postMessage oder über das progress-Ereignis der BackgroundFetchRegistration.
Bei einem Abbruch ist event.registration.failureReason gleich "aborted". Ein normaler Fehlschlag löst stattdessen backgroundfetchfail aus, ein erfolgreicher Abschluss backgroundfetchsuccess.
updateUI() gibt es nur bei BackgroundFetchUpdateUIEvent (Erfolg/Fehlschlag), nicht in diesem Ereignis.
Ohne event.waitUntil() kann der Browser den Service Worker beenden, bevor asynchrones Aufräumen fertig ist.
Nach dem Abbruch sind die Antworten der Anfragen nicht mehr zuverlässig über matchAll() abrufbar. Schon geladene Daten gelten als verworfen.

Siehe auch

ServiceWorkerGlobalScope: backgroundfetchclick ServiceWorkerGlobalScope: backgroundfetchfail ServiceWorkerGlobalScope: backgroundfetchsuccess ServiceWorkerGlobalScope: cookiechange ServiceWorkerGlobalScope: fetch