BackgroundFetchUpdateUIEvent.updateUI() — Methode · JavaScript-Referenz

Signatur

BackgroundFetchUpdateUIEvent.prototype.updateUI(options)

Beschreibung

Die Methode updateUI() steht im Service Worker innerhalb der Ereignisse backgroundfetchsuccess und backgroundfetchfail zur Verfügung. Mit ihr ändert man die Anzeige, die der Browser zu einem Hintergrundabruf zeigt, zum Beispiel die Download-Benachrichtigung oder die Fortschrittsleiste. So erfährt der Nutzer, ob der Download geklappt hat, auch wenn die Seite längst geschlossen ist.

Typisch ist dieser Ablauf: Der Service Worker bekommt das Ereignis, speichert die heruntergeladenen Antworten mit der Cache API und ruft danach event.updateUI({ title: 'Fertig!' }) auf. Ohne diesen Aufruf zeigt der Browser nur einen allgemeinen Status an.

Pro Ereignis darf updateUI() nur einmal aufgerufen werden. Weil BackgroundFetchUpdateUIEvent von BackgroundFetchEvent und damit von ExtendableEvent erbt, kann man langsame Arbeiten wie das Befüllen des Caches mit event.waitUntil() absichern. Der Aufruf von updateUI() selbst muss erfolgen, solange das Ereignis noch aktiv ist.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt mit den neuen Angaben für die Anzeige.
$options.title	string		Neuer Titel, z. B. `'Podcast-Folge heruntergeladen'`.
$options.icons	Array<{src: string, sizes?: string, type?: string, label?: string}>		Liste von Bildangaben im Stil des Web-App-Manifests. `src` ist Pflicht, `sizes` (z. B. `'192x192'`), `type` (MIME-Typ) und `label` sind optional. Der Browser wählt das passende Symbol aus.

Beispiele

Erfolgreichen Download speichern und die Anzeige ändern

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

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

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

    // Anzeige nur einmal ändern
    await event.updateUI({
      title: 'Folge 42 ist bereit zum Anhören',
      icons: [{ src: '/icons/done-192.png', sizes: '192x192', type: 'image/png' }]
    });
  })());
});

Fehler im Download anzeigen

// service-worker.js
self.addEventListener('backgroundfetchfail', (event) => {
  const { failureReason, id } = event.registration;
  console.log(`Abruf ${id} fehlgeschlagen:`, failureReason);

  event.waitUntil(
    event.updateUI({
      title: failureReason === 'quota-exceeded'
        ? 'Download abgebrochen: zu wenig Speicherplatz'
        : 'Download fehlgeschlagen – bitte erneut versuchen'
    })
  );
});

Abruf episode-42 fehlgeschlagen: bad-status

Zweiten Aufruf absichern

self.addEventListener('backgroundfetchsuccess', (event) => {
  event.waitUntil((async () => {
    await event.updateUI({ title: 'Fertig' });
    try {
      // Ein zweiter Aufruf ist nicht erlaubt
      await event.updateUI({ title: 'Doch nochmal' });
    } catch (err) {
      console.log(err.name);
    }
  })());
});

InvalidStateError

// Wichtig · Fallstricke

Nur einmal pro Ereignis: Ruft man updateUI() ein zweites Mal auf, wird das Promise mit InvalidStateError abgelehnt. Das gilt auch für selbst erzeugte Ereignisse (isTrusted === false).
Nur im Service Worker: Die Methode gibt es nur in backgroundfetchsuccess und backgroundfetchfail. In backgroundfetchabort und backgroundfetchclick ist das Ereignis ein normales BackgroundFetchEvent ohne updateUI().
Lebensdauer: Wenn man vorher asynchron arbeitet, das Ganze in event.waitUntil() packen. Sonst kann der Service Worker beendet werden, bevor die Anzeige geändert ist.
Symbole: Symbole, die nicht geladen werden können, ignoriert der Browser ohne Fehlermeldung. Am besten Symbole von derselben Herkunft nehmen und vorher im Cache ablegen.
Kompatibilität: Die API ist experimentell und funktioniert nur in Chromium-Browsern mit sicherem Kontext (HTTPS). Vorher prüfen, ob sie da ist, z. B. mit 'BackgroundFetchManager' in self, und sonst auf normales fetch() ausweichen.

Siehe auch

new BackgroundFetchUpdateUIEvent() BackgroundFetchManager.getIds() BackgroundFetchManager.fetch() BackgroundFetchManager.get() BackgroundFetchRegistration.abort()