BackgroundFetchRegistration.downloaded — Eigenschaft · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.downloaded

Beschreibung

Die schreibgeschützte Eigenschaft downloaded eines BackgroundFetchRegistration-Objekts gibt an, wie viele Bytes bisher über alle Anfragen eines Background Fetch heruntergeladen wurden. Zu Beginn ist der Wert 0. Während der Übertragung steigt er an.

Gebraucht wird die Eigenschaft vor allem für Fortschrittsanzeigen. Zusammen mit downloadTotal lässt sich ein Prozentwert berechnen. Bei jeder Änderung von downloaded löst die Registrierung das Ereignis progress aus. Man kann also mit registration.addEventListener("progress", handler) oder registration.onprogress auf neue Werte reagieren, ohne ständig nachfragen zu müssen.

Die Registrierung erhält man entweder direkt als Rückgabewert von BackgroundFetchManager.fetch() oder später über registration.backgroundFetch.get(id). Das funktioniert sowohl auf der Seite als auch im Service Worker, etwa in den Ereignissen backgroundfetchsuccess und backgroundfetchfail.

Rückgabewert

Typ

number

Beschreibung

Die Zahl der bisher heruntergeladenen Bytes als nicht-negative Ganzzahl (unsigned long long). Zu Beginn ist der Wert 0.

Beispiele

Fortschritt eines Background Fetch anzeigen

// Auf der Seite, wenn ein Service Worker aktiv ist
const swReg = await navigator.serviceWorker.ready;

const bgFetch = await swReg.backgroundFetch.fetch(
  'film-download',
  ['/media/film.mp4'],
  { title: 'Film wird geladen', downloadTotal: 250 * 1024 * 1024 }
);

console.log('Start:', bgFetch.downloaded);

bgFetch.addEventListener('progress', () => {
  if (!bgFetch.downloadTotal) return; // Gesamtgröße nicht bekannt
  const prozent = Math.round((bgFetch.downloaded / bgFetch.downloadTotal) * 100);
  console.log(`Fortschritt: ${prozent} %`);
});

Start: 0 Fortschritt: 3 % Fortschritt: 7 % ...

Laufenden Download nach einem Neuladen der Seite wiederfinden

const swReg = await navigator.serviceWorker.ready;
const bgFetch = await swReg.backgroundFetch.get('film-download');

if (bgFetch) {
  const mb = (bgFetch.downloaded / 1024 / 1024).toFixed(1);
  console.log(`Bereits geladen: ${mb} MB`);

  // Alternative mit der on-Property
  bgFetch.onprogress = () => {
    document.querySelector('#status').textContent =
      `${(bgFetch.downloaded / 1024 / 1024).toFixed(1)} MB geladen`;
  };
}

Bereits geladen: 42.3 MB

Abschluss im Service Worker protokollieren

// service-worker.js
self.addEventListener('backgroundfetchsuccess', (event) => {
  const reg = event.registration;
  console.log(`${reg.id}: ${reg.downloaded} Bytes geladen`);
  event.waitUntil(event.updateUI({ title: 'Download abgeschlossen' }));
});

film-download: 262144000 Bytes geladen

// Wichtig · Fallstricke

Experimentell: Die Background Fetch API gibt es derzeit nur in Chromium-Browsern. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man die Unterstützung prüfen, zum Beispiel mit 'BackgroundFetchManager' in self. Außerdem braucht die API einen sicheren Kontext (HTTPS) und einen aktiven Service Worker.
downloadTotal kann 0 sein, wenn beim Aufruf von fetch() keine Gesamtgröße angegeben wurde. Vor der Prozentberechnung sollte man das prüfen, sonst droht eine Division durch null (Infinity bzw. NaN).
Ist der angegebene downloadTotal kleiner als die tatsächliche Datenmenge, bricht der Browser den Fetch ab.
Der Wert zählt nur die Antwort-Daten. Hochgeladene Bytes stehen in uploaded.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und löst im Strict Mode einen TypeError aus.

Siehe auch

BackgroundFetchRegistration.downloadTotal BackgroundFetchRegistration.id BackgroundFetchRegistration.uploaded BackgroundFetchRegistration.result BackgroundFetchRegistration.uploadTotal