new BackgroundFetchUpdateUIEvent() — Methode · JavaScript-Referenz

Signatur

new BackgroundFetchUpdateUIEvent(type, options)

Beschreibung

Der Konstruktor BackgroundFetchUpdateUIEvent() erzeugt ein Ereignisobjekt vom Typ BackgroundFetchUpdateUIEvent. Dieses Interface erweitert BackgroundFetchEvent (und damit ExtendableEvent). Der Browser verschickt es im Service Worker als backgroundfetchsuccess oder backgroundfetchfail, sobald ein mit der Background Fetch API gestarteter Download abgeschlossen oder fehlgeschlagen ist.

In der Praxis rufst du den Konstruktor fast nie selbst auf. Du bekommst das Objekt als Argument deines Event-Handlers und nutzt dann event.registration, um auf die Antworten zuzugreifen, und event.updateUI(), um Titel und Symbole der Fortschrittsanzeige des Browsers zu ändern, z. B. von „Wird heruntergeladen…“ auf „Folge 12 bereit“.

Einen eigenen Aufruf des Konstruktors brauchst du vor allem in Tests, etwa um Handler-Logik mit einem nachgebauten Ereignis zu prüfen. Dafür musst du ein echtes BackgroundFetchRegistration-Objekt übergeben. Der Konstruktor steht nur im Service-Worker-Kontext (ServiceWorkerGlobalScope) zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, groß-/kleinschreibungssensitiv. Der Browser verwendet `"backgroundfetchsuccess"` oder `"backgroundfetchfail"`.
$options Pflicht	object		Initialisierungsobjekt. Es enthält alle Felder von `ExtendableEventInit` (`bubbles`, `cancelable`, `composed`) und zusätzlich: `registration` (`BackgroundFetchRegistration`, Pflicht): die Registrierung des Background Fetch, zu dem das Ereignis gehört.

Rückgabewert

Typ

BackgroundFetchUpdateUIEvent

Beschreibung

Ein neues BackgroundFetchUpdateUIEvent-Objekt. Seine Eigenschaft registration verweist auf die übergebene Registrierung.

Beispiele

Typische Nutzung: UI nach erfolgreichem Download aktualisieren

// sw.js – der Browser erzeugt das Event selbst
self.addEventListener('backgroundfetchsuccess', (event) => {
  const bgFetch = event.registration;

  event.waitUntil((async () => {
    // Alle Antworten im Cache speichern
    const cache = await caches.open('podcasts');
    const records = await bgFetch.matchAll();

    await Promise.all(records.map(async (record) => {
      const response = await record.responseReady;
      await cache.put(record.request, response);
    }));

    // Download-Oberfläche des Browsers anpassen
    await event.updateUI({ title: `Folge „${bgFetch.id}“ ist bereit` });
  })());
});

Fehlschlag melden mit backgroundfetchfail

// 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',
      icons: [{ src: '/icons/error-192.png', sizes: '192x192', type: 'image/png' }]
    })
  );
});

Background Fetch folge-12 fehlgeschlagen: bad-status

Konstruktor manuell aufrufen (z. B. für Tests im Service Worker)

// sw.js – setzt eine bestehende Registrierung mit der ID 'folge-12' voraus
const testeHandler = async () => {
  const registration = await self.registration.backgroundFetch.get('folge-12');
  if (!registration) return;

  const event = new BackgroundFetchUpdateUIEvent('backgroundfetchsuccess', {
    registration
  });

  console.log(event.type, event.registration.id, event.isTrusted);

  try {
    await event.updateUI({ title: 'Test' });
  } catch (err) {
    // Synthetische Events dürfen die UI nicht ändern
    console.log(err.name);
  }
};

testeHandler();

backgroundfetchsuccess folge-12 false InvalidStateError

// Wichtig · Fallstricke

Experimentell und eingeschränkt verfügbar: Die Background Fetch API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Prüfe vorher mit 'BackgroundFetchManager' in self bzw. 'backgroundFetch' in registration.
Den Konstruktor gibt es nur im Service Worker. Im Fenster-Kontext führt new BackgroundFetchUpdateUIEvent() zu einem ReferenceError.
options.registration ist Pflicht. Fehlt es, wirft der Konstruktor einen TypeError. Ein einfaches Objekt reicht nicht, es muss ein echtes BackgroundFetchRegistration sein.
Bei selbst erzeugten Ereignissen ist isTrusted false. updateUI() gibt dann ein abgelehntes Promise mit InvalidStateError zurück. Dasselbe passiert, wenn du updateUI() ein zweites Mal aufrufst oder erst, nachdem das Ereignis nicht mehr aktiv ist. Rufe es deshalb innerhalb von event.waitUntil() auf.
Nur die Ereignisse backgroundfetchsuccess und backgroundfetchfail verwenden dieses Interface. backgroundfetchabort und backgroundfetchclick liefern ein normales BackgroundFetchEvent ohne updateUI().
Große Icons, die du über updateUI() übergibst, lädt der Browser zusätzlich herunter. Nimm deshalb kleine, gecachte Bilder.

Siehe auch

BackgroundFetchUpdateUIEvent.updateUI() new BackgroundFetchEvent() new CharacterBoundsUpdateEvent() new PaymentRequestUpdateEvent() new TextFormatUpdateEvent()