HTMLProgressElement.position — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLProgressElement.position

Beschreibung

Die Eigenschaft position kann nur gelesen werden. Sie liefert den Fortschritt eines <progress>-Elements als Gleitkommazahl. Bei einem bestimmten Fortschrittsbalken (das Attribut value ist gesetzt) entspricht der Wert dem Quotienten value / max und liegt immer zwischen 0 und 1.

Bei einem unbestimmten Fortschrittsbalken fehlt das value-Attribut. Dann gibt position den Wert -1 zurück. Daran erkennt man ohne weitere Prüfung, ob der Balken gerade eine Animation für „läuft noch, Dauer unbekannt“ zeigt.

Nützlich ist position, wenn man einen normierten Prozentwert braucht, etwa für Textanzeigen („42 %“), ARIA-Beschriftungen oder eigene Visualisierungen. Die Rechnung mit max muss man dann nicht selbst schreiben. Der Browser begrenzt dabei value automatisch auf den Bereich 0 bis max.

Rückgabewert

Typ

number

Beschreibung

Bei einem bestimmten Balken eine Gleitkommazahl von 0 bis 1 (value / max), bei einem unbestimmten Balken -1.

Beispiele

Fortschritt als Prozentwert anzeigen

// HTML: <progress id="upload" value="30" max="120"></progress>
const bar = document.querySelector('#upload');
const prozent = Math.round(bar.position * 100);
console.log(`${prozent} %`);

25 %

Unbestimmten Zustand erkennen

const bar = document.createElement('progress');
console.log(bar.position); // kein value-Attribut, also unbestimmt

bar.value = 0.5; // max ist standardmäßig 1
console.log(bar.position);

bar.removeAttribute('value');
console.log(bar.position === -1 ? 'unbestimmt' : 'bestimmt');

-1 0.5 unbestimmt

Download-Fortschritt mit fetch und Statustext

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

const download = async (url) => {
  const res = await fetch(url);
  const total = Number(res.headers.get('Content-Length'));
  if (total) bar.max = total; else bar.removeAttribute('value');

  const reader = res.body.getReader();
  let geladen = 0;
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    geladen += value.length;
    if (total) bar.value = geladen;
    status.textContent = bar.position === -1
      ? `${geladen} Bytes geladen …`
      : `${(bar.position * 100).toFixed(1)} % geladen`;
  }
};

download('/daten/gross.zip');

// Wichtig · Fallstricke

position kann nur gelesen werden. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Den Fortschritt ändert man über value und max.
Den Wert -1 für den unbestimmten Zustand sollte man vor der Umrechnung in Prozent prüfen. Sonst erscheint „-100 %“.
Wer value = 0 setzt, macht den Balken zu einem bestimmten Balken mit position = 0. Zurück in den unbestimmten Zustand kommt man nur mit removeAttribute('value').
Ungültige oder nicht positive Werte für max werden als 1 behandelt. Werte für value über max werden auf max begrenzt, deshalb ist position nie größer als 1.
Die Eigenschaft wird in allen modernen Browsern unterstützt. Der Internet Explorer kennt sie ab Version 10.

Siehe auch

HTMLOutputElement.validity HTMLProgressElement.labels HTMLProgressElement.max HTMLProgressElement.value HTMLAreaElement.origin