ProgressEvent.loaded — Eigenschaft · JavaScript-Referenz

Signatur

ProgressEvent.loaded

Beschreibung

ProgressEvent.loaded ist eine schreibgeschützte Eigenschaft eines ProgressEvent. Sie gibt an, wie viel von einem laufenden Vorgang schon erledigt ist. Bei HTTP-Übertragungen über XMLHttpRequest sind das die bisher übertragenen Bytes. Beim Lesen mit FileReader sind es die bereits gelesenen Bytes.

Zusammen mit ProgressEvent.total und ProgressEvent.lengthComputable lässt sich daraus ein Fortschritt in Prozent berechnen, etwa für Fortschrittsbalken bei Datei-Uploads, großen Downloads oder beim Einlesen lokaler Dateien. Ist die Gesamtgröße unbekannt (lengthComputable === false), zeigt loaded nur die absolute Menge an. Dann eignet sich eher eine Anzeige wie „2,3 MB geladen“.

Beim Herunterladen zählt loaded die Bytes des Antwort-Rumpfs, wie sie übertragen werden. Bei komprimierten Antworten (z. B. Content-Encoding: gzip) ist das die komprimierte Größe. Für Uploads meldet man sich an den Events von xhr.upload an, nicht an denen von xhr selbst.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Zahl (in der Regel eine ganze Zahl von Bytes) für die bereits übertragene oder verarbeitete Datenmenge. Bei selbst erzeugten Events ist der Standardwert 0.

Beispiele

Download-Fortschritt mit XMLHttpRequest

const xhr = new XMLHttpRequest();
xhr.open('GET', '/dateien/video.mp4');
xhr.responseType = 'blob';

xhr.addEventListener('progress', (event) => {
  if (event.lengthComputable) {
    const prozent = Math.round((event.loaded / event.total) * 100);
    console.log(`Geladen: ${prozent} %`);
  } else {
    console.log(`Geladen: ${(event.loaded / 1024).toFixed(1)} KB`);
  }
});

xhr.addEventListener('load', () => console.log('Download fertig'));
xhr.send();

Geladen: 12 % Geladen: 47 % Geladen: 100 % Download fertig

Upload-Fortschritt in einem <progress>-Element anzeigen

const input = document.querySelector('#datei');
const balken = document.querySelector('progress');

input.addEventListener('change', () => {
  const formData = new FormData();
  formData.append('datei', input.files[0]);

  const xhr = new XMLHttpRequest();
  // Upload-Events hängen an xhr.upload!
  xhr.upload.onprogress = (event) => {
    if (event.lengthComputable) {
      balken.max = event.total;
      balken.value = event.loaded;
    }
  };
  xhr.upload.onload = () => console.log('Upload abgeschlossen');
  xhr.open('POST', '/api/upload');
  xhr.send(formData);
});

Upload abgeschlossen

Lokale Datei mit FileReader einlesen

const leseDatei = (file) => new Promise((resolve, reject) => {
  const reader = new FileReader();
  reader.onprogress = (event) => {
    console.log(`${event.loaded} von ${event.total} Bytes gelesen`);
  };
  reader.onload = () => resolve(reader.result);
  reader.onerror = () => reject(reader.error);
  reader.readAsArrayBuffer(file);
});

document.querySelector('#datei').addEventListener('change', async (e) => {
  const buffer = await leseDatei(e.target.files[0]);
  console.log('Fertig:', buffer.byteLength, 'Bytes');
});

1048576 von 3145728 Bytes gelesen 3145728 von 3145728 Bytes gelesen Fertig: 3145728 Bytes

Eigenes ProgressEvent erzeugen

const event = new ProgressEvent('progress', {
  lengthComputable: true,
  loaded: 250,
  total: 1000
});

console.log(event.loaded / event.total);
event.loaded = 999; // wird ignoriert, schreibgeschützt
console.log(event.loaded);

0.25 250

// Wichtig · Fallstricke

Vor dem Teilen immer lengthComputable prüfen: Ist die Gesamtgröße unbekannt (z. B. kein Content-Length-Header oder Chunked-Transfer), ist total gleich 0. loaded / total ergibt dann Infinity oder NaN.
Komprimierte Antworten: loaded zählt die übertragenen, also komprimierten Bytes. Die Größe der entpackten Antwort kann deutlich größer sein.
Upload und Download sind getrennt: Den Upload-Fortschritt melden nur die Events von xhr.upload. Handler dafür müssen vor send() registriert werden. Außerdem können sie bei CORS einen Preflight auslösen.
Schreibgeschützt: Zuweisungen werden stillschweigend ignoriert (im Strict Mode gibt es einen TypeError). Eigene Werte setzt man über den Konstruktor new ProgressEvent().
Häufigkeit: Browser feuern progress etwa alle 50 ms. Aufwendige DOM-Aktualisierungen sollte man trotzdem sparsam halten, z. B. mit requestAnimationFrame.
Fetch-API: fetch() erzeugt keine ProgressEvents. Den Fortschritt misst man dort selbst, indem man response.body.getReader() ausliest und die Byte-Anzahlen der Blöcke aufsummiert.
Die Eigenschaft wird von allen modernen Browsern unterstützt und ist auch in Web Workern verfügbar.

Siehe auch

ProgressEvent ProgressEvent.total ProgressEvent.lengthComputable XMLHttpRequest XMLHttpRequest.upload FileReader