HTMLProgressElement.max — Eigenschaft · JavaScript-Referenz

Signatur

HTMLProgressElement.max

Beschreibung

Die Eigenschaft max spiegelt das HTML-Attribut max eines <progress>-Elements. Sie legt fest, welcher Wert von value für „100 % erledigt“ steht. Die untere Grenze ist immer 0 und lässt sich nicht ändern. Die Eigenschaft ist vom Typ double. Fehlt das Attribut oder ist es ungültig, liefert sie 1.

Praktisch ist max, wenn der Fortschritt in echten Einheiten angezeigt werden soll, statt ihn vorher in einen Bruch zwischen 0 und 1 umzurechnen. Beispiele sind die Gesamtgröße eines Uploads in Bytes, die Zahl der Schritte in einem Assistenten oder die Länge eines Videos in Sekunden. Der Browser berechnet den Füllstand dann selbst als value / max. Das Ergebnis steht auch in der schreibgeschützten Eigenschaft position.

Zu beachten:

Nur positive Werte werden übernommen. Setzt man 0 oder einen negativen Wert, wird die Zuweisung stillschweigend ignoriert und der bisherige Wert bleibt erhalten. Nicht endliche Werte wie NaN oder Infinity lösen einen TypeError aus.
value wird auf max begrenzt. Ist das Attribut value größer als max, liefert die Eigenschaft value den Wert von max. Das Attribut selbst bleibt unverändert.
Wenn man max setzt, bleibt ein unbestimmter Fortschrittsbalken (ohne Attribut value) unbestimmt. Bestimmt wird er erst, wenn value gesetzt wird.

Parameter

Name	Typ	Default	Beschreibung
$newValue	number	1	Nur beim Setzen: neue obere Grenze. Muss endlich und größer als `0` sein. Der Wert wird als Attribut `max` ins HTML zurückgeschrieben.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle obere Grenze als Gleitkommazahl. Fehlt das Attribut, lässt es sich nicht auslesen oder ist es ≤ 0, wird 1 zurückgegeben.

Beispiele

Standardwert und Zusammenspiel mit value

const bar = document.createElement('progress');
console.log(bar.max);      // kein Attribut -> Standardwert

bar.max = 200;
bar.value = 50;
console.log(bar.position); // 50 / 200

bar.value = 500;           // größer als max
console.log(bar.value);    // wird auf max begrenzt
console.log(bar.getAttribute('max'));

1 0.25 200 "200"

Upload-Fortschritt in Bytes anzeigen

// HTML: <input type="file" id="file"> <progress id="upload"></progress>
const input = document.querySelector('#file');
const bar = document.querySelector('#upload');

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

  const xhr = new XMLHttpRequest();
  xhr.upload.addEventListener('progress', (event) => {
    if (event.lengthComputable) {
      bar.max = event.total;    // Gesamtgröße in Bytes
      bar.value = event.loaded; // bereits übertragene Bytes
    }
  });
  xhr.upload.addEventListener('load', () => console.log('Upload fertig'));
  xhr.open('POST', '/api/upload');
  xhr.send(file);
});

Upload fertig

Assistent mit Schritten und ungültige Zuweisungen

const steps = ['Konto', 'Adresse', 'Zahlung', 'Bestätigung'];
const bar = document.createElement('progress');
bar.max = steps.length;

const goTo = (index) => {
  bar.value = index + 1;
  bar.textContent = `Schritt ${index + 1} von ${bar.max}`; // Fallback-Text
};
goTo(1);
console.log(bar.textContent);

bar.max = 0;   // wird ignoriert
bar.max = -5;  // wird ebenfalls ignoriert
console.log(bar.max);

try {
  bar.max = NaN;
} catch (err) {
  console.log(err.name);
}

Schritt 2 von 4 4 TypeError

// Wichtig · Fallstricke

Stilles Ignorieren: Die Zuweisung von 0 oder negativen Zahlen wirft keinen Fehler, bewirkt aber nichts. Wer max aus einer Berechnung übernimmt, etwa event.total bei einer leeren Datei, sollte den Wert vorher prüfen.
NaN/Infinity lösen einen TypeError aus. Deshalb Werte aus Formularfeldern mit Number() umwandeln und mit Number.isFinite() prüfen.
Wird max unter den aktuellen Wert von value gesetzt, zeigt der Balken 100 %. Das Attribut value behält trotzdem seinen ursprünglichen Wert. Das kann beim Auslesen mit getAttribute('value') überraschen.
Einen unbestimmten Zustand (animierter Balken) erreicht man nicht über max, sondern mit bar.removeAttribute('value').
Barrierefreiheit: Das Element meldet Screenreadern seinen Fortschritt selbst. Sinnvoll ist trotzdem ein zugehöriges <label> oder aria-label.
Wird von allen modernen Browsern unterstützt, im Internet Explorer ab Version 10.

Siehe auch

HTMLMeterElement.max HTMLOptGroupElement.label HTMLProgressElement.value HTMLProgressElement.labels HTMLProgressElement.position