HTMLProgressElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLProgressElement extends HTMLElement

Beschreibung

HTMLProgressElement ist die DOM-Schnittstelle für das HTML-Element <progress>. Sie erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt sie um Eigenschaften, mit denen sich der Fortschritt einer Aufgabe wie eines Datei-Uploads, eines Downloads oder eines mehrstufigen Formulars anzeigen und per Skript ändern lässt.

Die wichtigsten Eigenschaften sind:

value (number): der aktuelle Fortschritt, zwischen 0 und max. Entspricht dem Attribut value.
max (number): der Maximalwert, Standard ist 1. Muss größer als 0 sein.
position (number, nur lesbar): value / max als Bruch zwischen 0 und 1, bzw. -1, wenn die Anzeige unbestimmt ist.
labels (NodeList, nur lesbar): die dem Element zugeordneten <label>-Elemente.

Eine Fortschrittsanzeige ist unbestimmt (indeterminate), solange kein value-Attribut gesetzt ist. Browser zeigen dann meist eine Lade-Animation. Das ist nützlich, wenn die Gesamtdauer noch unbekannt ist. Mit removeAttribute('value') kommt man in diesen Zustand zurück. Das CSS-Pseudoklassen-Selektor :indeterminate passt genau auf diesen Zustand.

Für Messwerte innerhalb eines bekannten Bereichs, etwa Speicherbelegung oder Akkustand, ist <meter> bzw. HTMLMeterElement semantisch die richtige Wahl. <progress> ist ausschließlich für den Fortschritt einer Aufgabe gedacht.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0 (Attribut fehlt = unbestimmt)	Eigenschaft: aktueller Fortschritt. Werte unter `0` werden als `0` behandelt, Werte über `max` werden auf `max` begrenzt.
$max	number	1	Eigenschaft: Obergrenze des Fortschritts. Werte ≤ `0` werden ignoriert, dann gilt wieder `1`.
$position	number	-1 bei unbestimmtem Zustand	Nur lesbare Eigenschaft: `value / max` (zwischen 0 und 1) oder `-1`, wenn kein `value` gesetzt ist.
$labels	NodeList		Nur lesbare Eigenschaft: alle `<label>`-Elemente, die mit dem Element verknüpft sind.

Rückgabewert

Typ

HTMLProgressElement

Beschreibung

Das Element-Objekt, das z. B. document.createElement('progress') oder document.querySelector('progress') zurückgibt.

Beispiele

Fortschrittsbalken erzeugen und Eigenschaften lesen

const bar = document.createElement('progress');
bar.max = 200;
bar.value = 50;
document.body.append(bar);

console.log(bar instanceof HTMLProgressElement);
console.log(bar.position);

// Unbestimmter Zustand
bar.removeAttribute('value');
console.log(bar.position);

true 0.25 -1

Download-Fortschritt mit fetch und ReadableStream

// HTML: <label for="dl">Download:</label> <progress id="dl"></progress>
const bar = document.querySelector('#dl');

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

  if (total > 0) bar.max = total; // sonst bleibt der Balken unbestimmt

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
    received += value.length;
    if (total > 0) bar.value = received;
  }
  bar.value = bar.max;
  return new Blob(chunks);
};

download('/dateien/bericht.pdf')
  .then((blob) => console.log(`Fertig: ${blob.size} Bytes`));

Fertig: 482113 Bytes

Mehrstufiges Formular mit Beschriftung

// HTML: <label for="schritte">Schritt</label> <progress id="schritte" max="4" value="1"></progress>
const progress = document.getElementById('schritte');

const naechsterSchritt = () => {
  progress.value = Math.min(progress.value + 1, progress.max);
  progress.textContent = `${progress.value} von ${progress.max}`; // Fallback-Text
  progress.setAttribute('aria-valuetext', `Schritt ${progress.value} von ${progress.max}`);
};

naechsterSchritt();
console.log(progress.value, progress.labels[0].textContent);

2 Schritt

// Wichtig · Fallstricke

Unbestimmter Zustand: bar.value = 0 macht die Anzeige nicht unbestimmt, denn damit wird das Attribut gesetzt. Nutze stattdessen removeAttribute('value').
Kein min: Anders als <meter> beginnt <progress> immer bei 0.
Ungültige Werte: Wird max auf 0 oder einen negativen Wert gesetzt, ignoriert der Browser das und verwendet 1. Nicht-numerische Werte lösen beim Setzen einen TypeError aus, NaN und Infinity ebenso.
Performance: Bei sehr häufigen Aktualisierungen, z. B. pro Stream-Chunk, sollte das Setzen von value möglichst mit requestAnimationFrame gedrosselt werden.
Styling: Das Aussehen hängt stark vom Browser ab. Zum Anpassen braucht man herstellerspezifische Pseudoelemente wie ::-webkit-progress-value und ::-moz-progress-bar. Moderne Browser unterstützen accent-color.
Barrierefreiheit: Das Element hat automatisch die Rolle progressbar. Verknüpfe es trotzdem mit einem <label> oder aria-label.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Der Internet Explorer kennt das Element erst ab Version 10, labels dort gar nicht.

Siehe auch

HTMLParagraphElement HTMLPreElement HTMLAreaElement HTMLFormElement HTMLFrameSetElement