HTMLProgressElement.value — Eigenschaft · JavaScript-Referenz

Signatur

HTMLProgressElement.value

Beschreibung

Die Eigenschaft value der Schnittstelle HTMLProgressElement spiegelt das HTML-Attribut value eines <progress>-Elements wider. Sie gibt an, wie viel einer Aufgabe bereits erledigt ist, etwa bei einem Datei-Upload, einem Download oder einem mehrstufigen Formular.

Der Wert wird immer relativ zu max interpretiert (Standard: 1.0). Beim Lesen wird der Wert begrenzt: Ist das Attribut größer als max, erhältst du max. Ist es negativ oder ungültig, erhältst du 0. Das Attribut selbst behält beim Schreiben aber den Wert, den du gesetzt hast.

Wichtig ist der Unterschied zwischen bestimmtem und unbestimmtem Fortschritt. Fehlt das Attribut value, ist der Balken unbestimmt: Der Browser zeigt dann meist eine Animation an, und die Eigenschaft liefert 0. Sobald du value setzt, wird das Element bestimmt. Um wieder in den unbestimmten Zustand zu wechseln, musst du das Attribut mit removeAttribute('value') entfernen.

Ob ein Balken unbestimmt ist, prüfst du zuverlässig über position (liefert dann -1) oder in CSS über die Pseudoklasse :indeterminate.

Parameter

Name	Typ	Default	Beschreibung
$neuerWert	number		Nur beim Schreiben: der neue Fortschritt. Wird in eine Gleitkommazahl umgewandelt und als Attribut `value` gespeichert. Muss endlich sein.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle Fortschritt als double, begrenzt auf den Bereich 0 bis max. Liefert 0, wenn das Element unbestimmt ist (kein value-Attribut vorhanden).

Beispiele

Fortschritt lesen und setzen

// HTML: <progress id="bar" max="100"></progress>
const bar = document.getElementById('bar');

console.log(bar.value, bar.position); // unbestimmt
bar.value = 40;
console.log(bar.value, bar.position);

// Werte über max werden beim Lesen begrenzt
bar.value = 250;
console.log(bar.value, bar.getAttribute('value'));

0 -1 40 0.4 100 250

Upload-Fortschritt mit XMLHttpRequest anzeigen

const bar = document.querySelector('#upload-progress');
const input = document.querySelector('#file');

input.addEventListener('change', () => {
  const file = input.files[0];
  if (!file) return;

  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/api/upload');

  bar.removeAttribute('value'); // unbestimmt, bis erste Daten fließen

  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) {
      bar.max = e.total;
      bar.value = e.loaded;
    }
  });

  xhr.addEventListener('load', () => {
    bar.value = bar.max; // fertig
  });

  const data = new FormData();
  data.append('file', file);
  xhr.send(data);
});

Download-Fortschritt mit fetch und Streams

const loadWithProgress = async (url, bar) => {
  const response = await fetch(url);
  const total = Number(response.headers.get('Content-Length'));
  const reader = response.body.getReader();
  const chunks = [];
  let loaded = 0;

  if (total) bar.max = total; else bar.removeAttribute('value');

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
    loaded += value.length;
    if (total) bar.value = loaded;
  }

  bar.max = 1;
  bar.value = 1;
  return new Blob(chunks);
};

const blob = await loadWithProgress('/daten.json', document.querySelector('progress'));
console.log(`${blob.size} Bytes geladen`);

z. B. 48213 Bytes geladen

Zurück in den unbestimmten Zustand

const bar = document.querySelector('progress');
bar.value = 0.5;
console.log(bar.matches(':indeterminate'));

// value = 0 oder null reicht NICHT – das Attribut muss weg
bar.removeAttribute('value');
console.log(bar.matches(':indeterminate'), bar.position);

false true -1

// Wichtig · Fallstricke

Unbestimmt ≠ 0: Ein unbestimmter Balken liefert beim Lesen ebenfalls 0. Zum Unterscheiden prüfst du position === -1 oder :indeterminate. Mit bar.value = 0 oder null wird der Balken bestimmt (0 %), nicht unbestimmt. Unbestimmt wird er nur mit removeAttribute('value').
Nicht endliche Werte: Wird NaN, Infinity oder ein Wert zugewiesen, der zu NaN wird (z. B. 'abc'), wirft der Setter einen TypeError. Prüfe berechnete Werte (z. B. loaded / total mit total = 0) vorher mit Number.isFinite().
Begrenzung nur beim Lesen: Das Attribut speichert den gesetzten Wert unverändert. Nur die Eigenschaft und die Darstellung werden auf 0 bis max begrenzt.
Reihenfolge von max und value: Setze max vor value. So vermeidest du, dass ein Wert kurzzeitig am alten max gemessen und falsch angezeigt wird.
Barrierefreiheit: <progress> hat die Rolle progressbar. Gib dem Element eine Beschriftung, etwa über <label> oder aria-label. Fallback-Text zwischen den Tags zeigen nur sehr alte Browser an.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch vom Internet Explorer ab Version 10. Das Aussehen unterscheidet sich stark je nach Browser. Zum Gestalten brauchst du herstellerspezifische Pseudoelemente wie ::-webkit-progress-value und ::-moz-progress-bar.

Siehe auch

HTMLProgressElement.max HTMLProgressElement.labels HTMLProgressElement.position HTMLMeterElement.value HTMLOptionElement.value