BackgroundFetchRegistration.uploaded — Eigenschaft · JavaScript-Referenz

Signatur

BackgroundFetchRegistration.uploaded

Beschreibung

Die Eigenschaft uploaded eines BackgroundFetchRegistration-Objekts liefert als number die Anzahl der Bytes, die bei einem Background Fetch bereits erfolgreich an den Server gesendet wurden. Gezählt werden die Anfragekörper (Request-Bodies) aller Anfragen, die zu dieser Registrierung gehören. Zu Beginn ist der Wert 0.

Gebraucht wird die Eigenschaft vor allem für Fortschrittsanzeigen bei großen Uploads, etwa wenn Videos, Fotos oder Backups über die Background Fetch API übertragen werden, die auch dann weiterläuft, wenn die Seite geschlossen wird. Zusammen mit uploadTotal lässt sich daraus ein Prozentwert berechnen.

Ändert sich der Wert, löst die Registrierung das Ereignis progress aus. Das Ereignis lässt sich mit registration.addEventListener('progress', …) oder über registration.onprogress abonnieren. Den Download-Fortschritt geben die Eigenschaften downloaded und downloadTotal an.

Rückgabewert

Typ

number

Beschreibung

Anzahl der bisher erfolgreich hochgeladenen Bytes; nicht-negative Ganzzahl, anfangs 0.

Beispiele

Upload-Fortschritt einmalig abfragen

// Im Seitenkontext bei registriertem Service Worker
const swReg = await navigator.serviceWorker.ready;
const bgFetch = await swReg.backgroundFetch.get('video-upload');

if (bgFetch) {
  console.log(`Hochgeladen: ${bgFetch.uploaded} von ${bgFetch.uploadTotal} Bytes`);
}

Hochgeladen: 1048576 von 5242880 Bytes

Background Fetch mit Upload starten und Fortschritt anzeigen

const startUpload = async (file) => {
  const swReg = await navigator.serviceWorker.ready;
  const request = new Request('/api/upload', { method: 'POST', body: file });

  const bgFetch = await swReg.backgroundFetch.fetch('upload-' + Date.now(), [request], {
    title: `Lade ${file.name} hoch`,
    uploadTotal: file.size
  });

  const progressBar = document.querySelector('#upload-progress');
  bgFetch.addEventListener('progress', () => {
    if (!bgFetch.uploadTotal) return;
    const percent = Math.round((bgFetch.uploaded / bgFetch.uploadTotal) * 100);
    progressBar.value = percent;
    console.log(`Upload: ${percent} %`);
  });
};

document.querySelector('#file').addEventListener('change', (e) => {
  startUpload(e.target.files[0]);
});

Upload: 20 % Upload: 55 % Upload: 100 %

Über das onprogress-Property mit Feature-Erkennung

const swReg = await navigator.serviceWorker.ready;

if ('backgroundFetch' in swReg) {
  const ids = await swReg.backgroundFetch.getIds();
  for (const id of ids) {
    const reg = await swReg.backgroundFetch.get(id);
    reg.onprogress = () => {
      console.log(`${reg.id}: ${reg.uploaded} Bytes gesendet`);
    };
  }
} else {
  console.log('Background Fetch wird nicht unterstützt');
}

backup-42: 204800 Bytes gesendet

// Wichtig · Fallstricke

Kompatibilität: Die Background Fetch API ist experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera) verfügbar. Prüfen Sie die Unterstützung vorher mit 'backgroundFetch' in registration. Die API setzt einen sicheren Kontext (HTTPS) und einen aktiven Service Worker voraus.
uploadTotal ist 0, wenn beim Aufruf von fetch() kein Wert dafür angegeben wurde. Prüfen Sie das vor der Prozentberechnung, sonst teilen Sie durch null (Ergebnis NaN oder Infinity).
Die Eigenschaft ist schreibgeschützt; eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen Fehler.
Der Wert wird in Abschnitten aktualisiert, nicht Byte für Byte. Reagieren Sie deshalb auf das progress-Ereignis, statt die Eigenschaft ständig abzufragen (Polling).
Der Wert sagt nichts darüber aus, ob der Server die Daten erfolgreich verarbeitet hat. Das Ergebnis prüfen Sie über result, failureReason und die Ereignisse backgroundfetchsuccess bzw. backgroundfetchfail im Service Worker.

Siehe auch

BackgroundFetchRegistration.id BackgroundFetchRegistration.downloaded BackgroundFetchRegistration.uploadTotal BackgroundFetchRegistration.result BackgroundFetchRegistration.downloadTotal