Signatur
Beschreibung
Die Eigenschaft registration des Interfaces BackgroundFetchEvent gibt das BackgroundFetchRegistration-Objekt zurück, das zu dem Hintergrund-Download gehört, der das Event ausgelöst hat. Über dieses Objekt kommen Sie an die ID des Downloads (id), an den Fortschritt (downloaded, downloadTotal), an den Status (result, failureReason) und an die heruntergeladenen Einträge (match(), matchAll()).
Sie nutzen die Eigenschaft im Service Worker, und zwar in den Handlern für backgroundfetchabort und backgroundfetchclick. Diese Events sind vom Typ BackgroundFetchEvent. Die Events backgroundfetchsuccess und backgroundfetchfail sind vom Untertyp BackgroundFetchUpdateUIEvent, der ebenfalls registration anbietet und zusätzlich die Methode updateUI() mitbringt.
Meist geht es darum, anhand von registration.id zu erkennen, welcher Download gemeint ist. Danach öffnen Sie eine passende Seite, räumen Daten auf oder speichern die Antworten in einem Cache.
Rückgabewert
id, uploadTotal, uploaded, downloadTotal, downloaded, result, failureReason und recordsAvailable.Beispiele
Bei Klick auf die Download-Anzeige eine passende Seite öffnen
// service-worker.js
self.addEventListener('backgroundfetchclick', (event) => {
const { registration } = event;
// Download fertig: Ergebnisseite öffnen, sonst den Fortschritt anzeigen
const url = registration.result === 'success'
? `/podcasts/${registration.id}`
: `/downloads?id=${encodeURIComponent(registration.id)}`;
event.waitUntil(clients.openWindow(url));
});Nach einem Abbruch durch den Nutzer aufräumen
// service-worker.js
self.addEventListener('backgroundfetchabort', (event) => {
const { id } = event.registration;
console.log(`Download abgebrochen: ${id}`);
// Teilweise zwischengespeicherte Daten entfernen
event.waitUntil(caches.delete(`bgfetch-${id}`));
});Nach Erfolg alle Antworten in den Cache schreiben
// service-worker.js
self.addEventListener('backgroundfetchsuccess', (event) => {
const reg = event.registration;
event.waitUntil((async () => {
const cache = await caches.open(`bgfetch-${reg.id}`);
const records = await reg.matchAll();
await Promise.all(records.map(async (record) => {
const response = await record.responseReady;
await cache.put(record.request, response);
}));
console.log(`${records.length} Dateien gespeichert (${reg.downloaded} Bytes)`);
await event.updateUI({ title: 'Download abgeschlossen' });
})());
});// Wichtig · Fallstricke
- Experimentell: Die Background Fetch API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Prüfen Sie im Hauptskript vorher mit
'BackgroundFetchManager' in self, ob sie vorhanden ist. - Die Eigenschaft steht nur im Service Worker zur Verfügung und setzt einen sicheren Kontext (HTTPS) voraus.
registrationist schreibgeschützt. Ein neuer Wert wird ohne Fehlermeldung ignoriert.- Die heruntergeladenen Einträge lassen sich über
match()/matchAll()nur lesen, solangerecordsAvailableden Werttruehat. Speichern Sie die Antworten deshalb im Event-Handler innerhalb vonevent.waitUntil()dauerhaft ab. updateUI()gibt es nur beiBackgroundFetchUpdateUIEvent(Success-/Fail-Events), nicht beibackgroundfetchclickoderbackgroundfetchabort.