BackgroundFetchRegistration.matchAll() — Methode · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.prototype.matchAll(request, options)

Beschreibung

Mit matchAll() fragst du die einzelnen Anfrage-/Antwort-Paare einer laufenden oder abgeschlossenen Background-Fetch-Registrierung ab. Jedes Paar ist ein BackgroundFetchRecord. Er hat die Eigenschaft request und das Promise responseReady, das zur zugehörigen Response auflöst, sobald sie vorliegt.

Rufst du die Methode ohne Argumente auf, bekommst du alle Datensätze der Registrierung. Übergibst du einen Request oder eine URL, werden nur die passenden Einträge zurückgegeben. Der Abgleich funktioniert wie bei Cache.matchAll() und lässt sich über options anpassen, etwa mit ignoreSearch oder ignoreVary.

Typischerweise verwendest du die Methode im Service Worker, im Handler des Events backgroundfetchsuccess. Dort liest du die heruntergeladenen Antworten aus und speicherst sie dauerhaft in der Cache API. Auch aus der Seite heraus ist ein Aufruf möglich, z. B. über registration.backgroundFetch.get(id).

Parameter

Name	Typ	Default	Beschreibung
$request	Request \| string		Die Anfrage (als `Request`-Objekt oder URL), nach der gesucht wird. Fehlt sie, werden alle Datensätze zurückgegeben.
$options	object	{}	Optionen für den Abgleich: `ignoreSearch` (boolean, Standard `false`): Der Query-String der URL wird ignoriert. `ignoreMethod` (boolean, Standard `false`): Auch andere HTTP-Methoden als `GET`/`HEAD` gelten als Treffer. `ignoreVary` (boolean, Standard `false`): Der `Vary`-Header wird beim Abgleich ignoriert.

Rückgabewert

Typ

Promise<BackgroundFetchRecord[]>

Beschreibung

Ein Promise, das zu einem Array von BackgroundFetchRecord-Objekten auflöst. Passt kein Eintrag, ist das Array leer.

Beispiele

Alle Antworten nach erfolgreichem Download cachen (Service Worker)

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

  event.waitUntil((async () => {
    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' });
    console.log(`${records.length} Dateien gespeichert`);
  })());
});

3 Dateien gespeichert

Nur bestimmte Einträge per URL abfragen

// sw.js – z. B. im Event backgroundfetchsuccess
const findPodcastAudio = async (bgFetch) => {
  const records = await bgFetch.matchAll('/media/episode-42.mp3', {
    ignoreSearch: true // ?token=... ignorieren
  });
  if (records.length === 0) {
    console.log('Keine passende Datei gefunden');
    return null;
  }
  return records[0].responseReady;
};

Status eines Background Fetch von der Seite aus prüfen

const showProgress = async (id) => {
  const swReg = await navigator.serviceWorker.ready;
  if (!('backgroundFetch' in swReg)) {
    console.log('Background Fetch wird nicht unterstützt');
    return;
  }
  const bgFetch = await swReg.backgroundFetch.get(id);
  if (!bgFetch) return;

  const records = await bgFetch.matchAll();
  console.log('Angefragte URLs:', records.map((r) => r.request.url));
  console.log(`${bgFetch.downloaded} von ${bgFetch.downloadTotal} Bytes`);
};

showProgress('podcast-42');

Angefragte URLs: ['https://example.com/media/episode-42.mp3'] 1048576 von 52428800 Bytes

// Wichtig · Fallstricke

Experimentelle API: Background Fetch gibt es derzeit nur in Chromium-basierten Browsern. Firefox und Safari unterstützen sie nicht. Prüfe die Verfügbarkeit deshalb immer mit 'backgroundFetch' in registration.
Die API steht nur in sicheren Kontexten (HTTPS) und mit einem aktiven Service Worker zur Verfügung.
Ist recordsAvailable gleich false, weist das Promise mit einem InvalidStateError zurück. Das passiert z. B., nachdem die Events backgroundfetchsuccess bzw. backgroundfetchfail vollständig abgearbeitet wurden. Lies die Datensätze deshalb innerhalb von event.waitUntil() aus.
record.responseReady kann zurückweisen, wenn der Download abgebrochen wurde oder fehlgeschlagen ist. Behandle diesen Fall mit try/catch.
Für genau einen Treffer ist match() die bequemere Wahl.

Siehe auch

BackgroundFetchRegistration.match() BackgroundFetchRegistration.abort() BackgroundFetchManager.fetch() BackgroundFetchManager.get() BackgroundFetchManager.getIds()