BackgroundFetchRegistration.downloadTotal — Eigenschaft · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.downloadTotal

Beschreibung

Die schreibgeschützte Eigenschaft downloadTotal einer BackgroundFetchRegistration gibt an, wie viele Bytes der gesamte Background Fetch voraussichtlich herunterlädt. Die Zahl wird nicht vom Browser gemessen. Sie stammt aus der Option downloadTotal, die Sie beim Start mit BackgroundFetchManager.fetch() übergeben. Fehlt diese Option, ist der Wert 0.

Meist nutzen Sie die Eigenschaft zusammen mit downloaded, um einen Fortschritt in Prozent zu berechnen. Das geht zum Beispiel für einen eigenen Fortschrittsbalken in der Seite oder im Service Worker beim Ereignis progress. Der Browser selbst verwendet den Wert ebenfalls für seine eigene Fortschrittsanzeige, etwa in der Benachrichtigung zum Download.

Der Wert dient auch als Obergrenze: Lädt der Fetch mehr Bytes herunter als angegeben, bricht der Browser ihn ab. failureReason hat dann den Wert "total-download-exceeded". Geben Sie die Größe deshalb genau an oder lassen Sie sie ganz weg.

Rückgabewert

Typ

number

Beschreibung

Die erwartete Gesamtgröße in Bytes, wie sie bei fetch() in options.downloadTotal angegeben wurde. 0, wenn keine Größe angegeben wurde.

Beispiele

Background Fetch mit bekannter Gesamtgröße starten

const startPodcastDownload = async () => {
  const reg = await navigator.serviceWorker.ready;
  const bgFetch = await reg.backgroundFetch.fetch(
    'podcast-folge-42',
    ['/media/folge-42.mp3'],
    {
      title: 'Folge 42 wird heruntergeladen',
      downloadTotal: 58 * 1024 * 1024 // 58 MiB
    }
  );
  console.log('Erwartete Größe:', bgFetch.downloadTotal, 'Bytes');
};

startPodcastDownload();

Erwartete Größe: 60817408 Bytes

Fortschrittsbalken in der Seite aktualisieren

const bar = document.querySelector('progress');

const trackProgress = async (id) => {
  const reg = await navigator.serviceWorker.ready;
  const bgFetch = await reg.backgroundFetch.get(id);
  if (!bgFetch) return;

  const update = () => {
    if (bgFetch.downloadTotal > 0) {
      bar.max = bgFetch.downloadTotal;
      bar.value = bgFetch.downloaded;
    } else {
      bar.removeAttribute('value'); // unbestimmter Fortschritt
    }
  };

  update();
  bgFetch.addEventListener('progress', update);
};

trackProgress('podcast-folge-42');

Fortschritt in Prozent im Service Worker protokollieren

// service-worker.js
const logProgress = (bgFetch) => {
  const { downloaded, downloadTotal } = bgFetch;
  const percent = downloadTotal
    ? Math.round((downloaded / downloadTotal) * 100)
    : null;
  console.log(
    percent !== null
      ? `${bgFetch.id}: ${percent} %`
      : `${bgFetch.id}: ${downloaded} Bytes (Gesamtgröße unbekannt)`
  );
};

self.addEventListener('backgroundfetchsuccess', (event) => {
  logProgress(event.registration);
});

podcast-folge-42: 100 %

// Wichtig · Fallstricke

Experimentell: Die Background Fetch API gibt es nur in Chromium-Browsern wie Chrome, Edge und Opera. Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung vorher mit 'BackgroundFetchManager' in self. Außerdem ist ein sicherer Kontext (HTTPS) mit registriertem Service Worker nötig.
Division durch null: Ist downloadTotal gleich 0, wurde keine Größe angegeben. Prüfen Sie das vor jeder Prozentrechnung, sonst erhalten Sie Infinity oder NaN.
Harte Obergrenze: Ist der angegebene Wert zu klein, bricht der Browser den Download ab. failureReason ist dann "total-download-exceeded". Geben Sie die Größe im Zweifel lieber gar nicht an als falsch.
Der Wert ändert sich während des Downloads nicht. Nur downloaded, uploaded und die Status-Eigenschaften werden aktualisiert.

Siehe auch

BackgroundFetchRegistration BackgroundFetchRegistration.downloaded BackgroundFetchRegistration.uploadTotal BackgroundFetchRegistration.failureReason BackgroundFetchManager.fetch() BackgroundFetchRegistration.recordsAvailable