BackgroundFetchRegistration.match() — Methode · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.prototype.match(request, options)

Beschreibung

Mit match() sucht man innerhalb eines Background Fetch nach dem Datensatz (BackgroundFetchRecord) zu einer bestimmten Anfrage. Jeder Datensatz verbindet eine ursprüngliche Request mit einem Promise auf die zugehörige Response. So lässt sich gezielt auf eine einzelne Datei eines großen Downloads zugreifen, etwa auf ein bestimmtes Video-Segment oder eine Podcast-Episode.

Meist wird die Methode im Service Worker aufgerufen, im Handler des Events backgroundfetchsuccess oder backgroundfetchfail, aber auch auf der Seite über registration.backgroundFetch.get(id). Der Abgleich funktioniert wie bei Cache.match(): Verglichen werden URL und Methode. Mit options lässt sich der Vergleich lockern, zum Beispiel indem der Query-String ignoriert wird.

Braucht man alle passenden Datensätze, nimmt man stattdessen matchAll(). Zu beachten: Das Promise der responseReady-Eigenschaft eines Datensatzes wird erst erfüllt, wenn die Antwort tatsächlich vorliegt.

Parameter

Name	Typ	Default	Beschreibung
$request Pflicht	Request \| string		Die gesuchte Anfrage, entweder als `Request`-Objekt oder als URL-String.
$options	Object	{}	Optionen für den Abgleich: `ignoreSearch` (boolean, Query-String ignorieren), `ignoreMethod` (boolean, HTTP-Methode ignorieren), `ignoreVary` (boolean, den `Vary`-Header ignorieren). Standardwert jeweils `false`.

Rückgabewert

Typ

Promise<BackgroundFetchRecord | undefined>

Beschreibung

Ein Promise, das mit dem ersten passenden BackgroundFetchRecord erfüllt wird, oder mit undefined, wenn nichts passt. Es wird mit einem InvalidStateError abgelehnt, wenn die Datensätze nicht mehr verfügbar sind (recordsAvailable === false).

Beispiele

Einzelne Datei nach erfolgreichem Download in den Cache legen (Service Worker)

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

  event.waitUntil((async () => {
    const record = await bgFetch.match('/media/episode-1.mp3');
    if (!record) {
      console.log('Kein passender Datensatz gefunden');
      return;
    }
    const response = await record.responseReady;
    const cache = await caches.open('podcasts');
    await cache.put(record.request, response);
    console.log('Gespeichert:', record.request.url);
    await event.updateUI({ title: 'Episode 1 ist bereit!' });
  })());
});

Gespeichert: https://example.com/media/episode-1.mp3

Laufenden Background Fetch von der Seite aus abfragen

const checkDownload = async () => {
  const swReg = await navigator.serviceWorker.ready;
  const bgFetch = await swReg.backgroundFetch.get('movie-download');
  if (!bgFetch) return console.log('Kein Download mit dieser ID');

  const record = await bgFetch.match('/movies/trailer.mp4');
  console.log(record ? `Gefunden: ${record.request.url}` : 'Nicht Teil dieses Downloads');
};

checkDownload();

Gefunden: https://example.com/movies/trailer.mp4

Query-String beim Abgleich ignorieren

self.addEventListener('backgroundfetchsuccess', (event) => {
  event.waitUntil((async () => {
    // Heruntergeladen wurde '/data/report.json?v=42'
    const record = await event.registration.match('/data/report.json', {
      ignoreSearch: true
    });
    const response = await record.responseReady;
    const data = await response.json();
    console.log('Einträge im Bericht:', data.items.length);
  })());
});

Einträge im Bericht: 128

// Wichtig · Fallstricke

Experimentelle API: Die Background Fetch API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Vor dem Aufruf per 'BackgroundFetchManager' in self prüfen, ob sie vorhanden ist.
Funktioniert nur in einem sicheren Kontext (HTTPS) und mit einem registrierten Service Worker.
Ist recordsAvailable gleich false (etwa nachdem die Events backgroundfetchsuccess oder backgroundfetchfail fertig abgearbeitet sind), wird das Promise mit InvalidStateError abgelehnt. Die Antworten also direkt im Event-Handler innerhalb von event.waitUntil() verarbeiten und dauerhaft im Cache ablegen.
Bei mehreren Treffern liefert die Methode nur den ersten. Für alle Treffer matchAll() verwenden.
Das Promise von record.responseReady kann abgelehnt werden, wenn der Download dieser Datei fehlgeschlagen oder abgebrochen worden ist. Deshalb Fehler abfangen.

Siehe auch

Cache.match() BackgroundFetchRegistration.matchAll() BackgroundFetchRegistration.abort() BackgroundFetchManager.fetch() BackgroundFetchManager.get()