Signatur
Beschreibung
Die schreibgeschützte Eigenschaft result des Interfaces BackgroundFetchRegistration gibt den Endzustand eines Hintergrundabrufs (Background Fetch) an. Solange der Abruf noch läuft, ist der Wert ein leerer String "". Ist er abgeschlossen, lautet der Wert entweder "success" oder "failure".
Im Zusammenspiel mit failureReason lässt sich genau feststellen, warum ein Abruf fehlgeschlagen ist, z. B. wegen Abbruch durch Nutzer ("aborted"), fehlerhaftem HTTP-Status ("bad-status"), Netzwerkfehler ("fetch-error"), überschrittenem Speicherkontingent ("quota-exceeded") oder überschrittener downloadTotal-Angabe ("download-total-exceeded").
Die Eigenschaft ist vor allem im Service Worker in den Ereignissen backgroundfetchsuccess und backgroundfetchfail nützlich, sowie in der Seite über das progress-Ereignis der Registrierung, um den Abschluss zu erkennen und die Oberfläche anzupassen.
Rückgabewert
"", solange der Abruf nicht abgeschlossen ist; "success" bei erfolgreichem Abschluss aller Anfragen; "failure", wenn mindestens eine Anfrage fehlgeschlagen ist oder der Abruf abgebrochen wurde.Beispiele
Ergebnis im Service Worker auswerten
// sw.js
const handleFetchDone = async (event) => {
const reg = event.registration;
console.log(`Abruf ${reg.id}: ${reg.result}`);
if (reg.result === 'success') {
const records = await reg.matchAll();
const cache = await caches.open('downloads');
await Promise.all(records.map(async (record) => {
const response = await record.responseReady;
await cache.put(record.request, response);
}));
await event.updateUI({ title: 'Download abgeschlossen' });
} else {
console.warn('Grund:', reg.failureReason);
}
};
self.addEventListener('backgroundfetchsuccess', (event) => event.waitUntil(handleFetchDone(event)));
self.addEventListener('backgroundfetchfail', (event) => event.waitUntil(handleFetchDone(event)));Fortschritt und Abschluss in der Seite verfolgen
const startDownload = async () => {
const swReg = await navigator.serviceWorker.ready;
if (!('backgroundFetch' in swReg)) {
console.log('Background Fetch wird nicht unterstützt');
return;
}
const bgFetch = await swReg.backgroundFetch.fetch('film-1', ['/media/film-1.mp4'], {
title: 'Film herunterladen',
downloadTotal: 60 * 1024 * 1024
});
console.log('Start:', JSON.stringify(bgFetch.result)); // ""
bgFetch.addEventListener('progress', () => {
if (!bgFetch.result) {
console.log(`${Math.round(bgFetch.downloaded / bgFetch.downloadTotal * 100)} %`);
return;
}
console.log('Fertig mit Ergebnis:', bgFetch.result, bgFetch.failureReason);
});
};
startDownload();Status bestehender Abrufe prüfen
const listFetches = async () => {
const swReg = await navigator.serviceWorker.ready;
const ids = await swReg.backgroundFetch.getIds();
for (const id of ids) {
const reg = await swReg.backgroundFetch.get(id);
console.log(id, reg.result === '' ? 'läuft noch' : reg.result);
}
};
listFetches();// Wichtig · Fallstricke
- Kompatibilität: Die Background Fetch API ist experimentell und nur in Chromium-basierten Browsern verfügbar. Immer per
'backgroundFetch' in registrationprüfen und eine Alternative (normalesfetch()) bereithalten. Nur in sicheren Kontexten (HTTPS) nutzbar. - Ein leerer String ist falsy –
if (!reg.result)bedeutet „noch nicht abgeschlossen“, nicht „fehlgeschlagen“. "failure"sagt allein nichts über die Ursache aus; dafürfailureReasonauswerten. Bei Abbruch durch Nutzer wird zusätzlich das Ereignisbackgroundfetchabortstattbackgroundfetchfailausgelöst.- Die Eigenschaft ist schreibgeschützt; Zuweisungen werden ignoriert (im Strict Mode
TypeError). - Auch bei
"success"sollten die einzelnen Antworten (response.ok) geprüft werden, bevor sie im Cache landen.