BackgroundFetchUpdateUIEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface BackgroundFetchUpdateUIEvent extends BackgroundFetchEvent

Beschreibung

BackgroundFetchUpdateUIEvent gehört zur Background Fetch API. Das Interface beschreibt die Events, die der Browser im Service Worker auslöst, sobald ein mit BackgroundFetchManager.fetch() gestarteter Hintergrund-Download fertig ist: backgroundfetchsuccess, wenn alle Anfragen erfolgreich waren, und backgroundfetchfail, wenn mindestens eine fehlgeschlagen ist.

Das Interface erbt von BackgroundFetchEvent und hat damit die Eigenschaft registration (eine BackgroundFetchRegistration). Über sie liest du die heruntergeladenen Antworten mit matchAll() bzw. match() aus, um sie etwa in der Cache API oder IndexedDB zu speichern. Neu hinzu kommt die Methode updateUI(options). Sie ändert den Titel und die Symbole, die der Browser in seiner Download-Anzeige für diesen Vorgang zeigt, zum Beispiel „Podcast-Folge 42 ist bereit“.

Typischer Ablauf: Im Event-Handler rufst du event.waitUntil() mit einem Promise auf, das die Antworten speichert und danach event.updateUI() aufruft. updateUI() darf nur einmal und nur während das Event noch aktiv ist aufgerufen werden, also synchron im Handler oder innerhalb des an waitUntil() übergebenen Promises.

Einen eigenen Konstruktor gibt es zwar (new BackgroundFetchUpdateUIEvent(type, options)), er ist aber fast nur für Tests nützlich. Bei selbst erzeugten, nicht vertrauenswürdigen Events wird updateUI() abgelehnt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Events, üblicherweise `"backgroundfetchsuccess"` oder `"backgroundfetchfail"`.
$options Pflicht	{ registration: BackgroundFetchRegistration } & EventInit		Konstruktor-Parameter: Objekt mit der Pflicht-Eigenschaft `registration` sowie den üblichen `EventInit`-Feldern (`bubbles`, `cancelable`, `composed`).
$updateUI(options)	{ title?: string, icons?: Array<{ src: string, sizes?: string, type?: string, label?: string }> }	{}	Methode: `title` ist der neue Anzeigetitel, `icons` eine Liste von Bildquellen (wie im Web App Manifest). Beide Angaben sind optional.

Beispiele

Erfolgreichen Download cachen und Anzeige aktualisieren

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

  event.waitUntil((async () => {
    const cache = await caches.open('downloads');
    const records = await bgFetch.matchAll();

    // Alle Antworten in den Cache legen
    await Promise.all(records.map(async (record) => {
      const response = await record.responseReady;
      await cache.put(record.request, response);
    }));

    // Anzeige des Browsers anpassen (nur einmal erlaubt!)
    await event.updateUI({
      title: 'Folge 42 ist offline verfügbar',
      icons: [{ src: '/icons/done-192.png', sizes: '192x192', type: 'image/png' }]
    });
  })());
});

Fehlgeschlagenen Download melden

// sw.js
self.addEventListener('backgroundfetchfail', (event) => {
  const { id, failureReason } = event.registration;
  console.warn(`Background Fetch ${id} fehlgeschlagen:`, failureReason);

  event.waitUntil(
    event.updateUI({ title: 'Download fehlgeschlagen – bitte erneut versuchen' })
  );
});

Background Fetch podcast-42 fehlgeschlagen: fetch-error

Background Fetch auf der Seite starten (Auslöser für das Event)

// main.js – im Fenster-Kontext
const startDownload = async () => {
  const reg = await navigator.serviceWorker.ready;
  if (!('backgroundFetch' in reg)) {
    console.log('Background Fetch wird nicht unterstützt');
    return;
  }
  const bgFetch = await reg.backgroundFetch.fetch(
    'podcast-42',
    ['/media/episode-42.mp3'],
    { title: 'Lade Folge 42 …', downloadTotal: 60 * 1024 * 1024 }
  );
  console.log('Gestartet:', bgFetch.id);
};

startDownload();

Gestartet: podcast-42

Event manuell erzeugen (z. B. für Tests)

// sw.js – registration stammt aus einem echten Background Fetch
const reg = await self.registration.backgroundFetch.get('podcast-42');
const evt = new BackgroundFetchUpdateUIEvent('backgroundfetchsuccess', { registration: reg });
console.log(evt.type, evt.registration.id);

// Ein selbst erzeugtes Event ist nicht vertrauenswürdig → updateUI schlägt fehl
evt.updateUI({ title: 'Test' }).catch((err) => console.log(err.name));

backgroundfetchsuccess podcast-42 InvalidStateError

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Nur Chrome/Edge (ab 74) und andere Chromium-Browser unterstützen die Schnittstelle. Firefox und Safari kennen sie nicht. Prüfe deshalb vorher mit 'backgroundFetch' in registration, ob sie verfügbar ist, und sieh eine Ersatzlösung mit normalem fetch() vor.
Nur im Service Worker und nur in einem sicheren Kontext (HTTPS) verfügbar.
updateUI() wirft bzw. lehnt mit InvalidStateError ab, wenn du es ein zweites Mal aufrufst, wenn das Event nicht vertrauenswürdig ist (isTrusted === false) oder wenn das Event nicht mehr aktiv ist, etwa nach einem await außerhalb von waitUntil().
Die Events backgroundfetchabort und backgroundfetchclick sind keine BackgroundFetchUpdateUIEvents, sondern einfache BackgroundFetchEvents. Dort gibt es kein updateUI().
Rufe updateUI() erst auf, nachdem die Daten gespeichert sind. Nach dem Ende von waitUntil() kann der Browser die heruntergeladenen Antworten verwerfen.
Ob und wie der Browser Symbole anzeigt, hängt von der Plattform ab. Gib mehrere Größen an.

Siehe auch

Cache BackgroundFetchEvent BackgroundFetchManager BackgroundFetchRecord BackgroundFetchRegistration