Signatur
Beschreibung
Die Eigenschaft recordsAvailable des Interfaces BackgroundFetchRegistration zeigt an, ob Sie noch auf die Records eines Background Fetch zugreifen können. Ein Record ist ein BackgroundFetchRecord mit einer Anfrage und der zugehörigen Antwort. Solange der Wert true ist, liefern registration.match() und registration.matchAll() diese Records.
Beim Anlegen eines Background Fetch ist der Wert true. Auf false wechselt er, sobald der Browser die Records freigibt. Das passiert, nachdem das Abschluss-Ereignis im Service Worker vollständig abgearbeitet ist, also backgroundfetchsuccess, backgroundfetchfail oder backgroundfetchabort, einschließlich aller Promises aus event.waitUntil(). Danach sind die heruntergeladenen Daten über die Registrierung nicht mehr erreichbar.
Das hat eine praktische Folge: Sie müssen die Antworten innerhalb des Abschluss-Handlers dauerhaft speichern, zum Beispiel in der Cache-API oder in IndexedDB. Prüfen Sie recordsAvailable vor jedem Zugriff auf match() oder matchAll(). So vermeiden Sie einen InvalidStateError, besonders wenn eine Seite eine Registrierung später erneut über backgroundFetch.get() abfragt.
Rückgabewert
true, wenn Anfragen und Antworten noch zugänglich sind. false, wenn der Browser die Records bereits freigegeben hat.Beispiele
Antworten im Service Worker dauerhaft cachen
// sw.js
self.addEventListener('backgroundfetchsuccess', (event) => {
const bgFetch = event.registration;
event.waitUntil((async () => {
if (!bgFetch.recordsAvailable) {
console.warn('Records bereits freigegeben:', bgFetch.id);
return;
}
const cache = await caches.open('downloads');
const records = await bgFetch.matchAll();
await Promise.all(records.map(async (record) => {
const response = await record.responseReady;
await cache.put(record.request, response);
}));
await event.updateUI({ title: 'Download abgeschlossen' });
})());
});Status einer Registrierung von der Seite aus prüfen
const checkDownload = async (id) => {
const swReg = await navigator.serviceWorker.ready;
const bgFetch = await swReg.backgroundFetch.get(id);
if (!bgFetch) {
console.log('Keine Registrierung gefunden – vermutlich schon abgeschlossen.');
return;
}
console.log(`Ergebnis: ${bgFetch.result || 'läuft'}, Records verfügbar: ${bgFetch.recordsAvailable}`);
if (bgFetch.recordsAvailable) {
const record = await bgFetch.match('/videos/folge-1.mp4');
console.log('Record gefunden:', Boolean(record));
}
};
checkDownload('serie-staffel-1');Sicherer Zugriff mit Funktionsprüfung
const safeMatchAll = async (bgFetch) => {
if (!('BackgroundFetchRegistration' in self)) return [];
if (!bgFetch.recordsAvailable) return [];
try {
return await bgFetch.matchAll();
} catch (err) {
// InvalidStateError, falls die Records inzwischen freigegeben wurden
console.error(err.name);
return [];
}
};// Wichtig · Fallstricke
- Experimentelle API: Nur Chromium-basierte Browser unterstützen sie (Chrome und Edge ab Version 74). Firefox und Safari kennen sie nicht. Prüfen Sie die Unterstützung vorab, etwa mit
'backgroundFetch' in ServiceWorkerRegistration.prototype. - Die API funktioniert nur in einem sicheren Kontext (HTTPS) und nur mit einem registrierten Service Worker.
- Nachdem der Abschluss-Handler durchgelaufen ist, wird
recordsAvailabledauerhaftfalse. Wenn Sie die Antworten nicht innerhalb vonevent.waitUntil()sichern, gehen sie verloren. - Rufen Sie
match()odermatchAll()auf, während der Wertfalseist, wird das Promise mit einemInvalidStateError(DOMException) abgelehnt. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert.