HTMLProgressElement.labels — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLProgressElement.labels

Beschreibung

Die Eigenschaft labels liefert alle <label>-Elemente, die mit einem <progress>-Element verknüpft sind. Ein Label gilt als zugeordnet, wenn sein for-Attribut der id des Fortschrittsbalkens entspricht oder wenn das <progress>-Element innerhalb des Labels steht (und dort das erste beschriftbare Element ist).

Nützlich ist das vor allem, wenn du die Beschriftung eines Fortschrittsbalkens per Skript anpassen willst, etwa um den aktuellen Prozentwert anzuzeigen („Upload: 42 %“). Ebenso hilft es bei Barrierefreiheits-Prüfungen, weil du damit schnell feststellst, ob ein Fortschrittsbalken überhaupt eine sichtbare Beschriftung hat.

Die zurückgegebene NodeList ist live: Kommen Labels hinzu oder fallen weg, ist das sofort in der Liste zu sehen. Die Eigenschaft selbst ist schreibgeschützt. Ist kein Label zugeordnet, bekommst du eine leere NodeList (Länge 0) und nicht null.

Rückgabewert

Typ

NodeList

Beschreibung

Live-NodeList mit den zugeordneten HTMLLabelElement-Objekten in Dokumentreihenfolge. Ohne zugeordnete Labels ist sie leer.

Beispiele

Labels über das for-Attribut auslesen

// HTML:
// <label for="upload">Upload-Fortschritt</label>
// <progress id="upload" max="100" value="30"></progress>

const progress = document.getElementById('upload');

for (const label of progress.labels) {
  console.log(label.textContent);
}
console.log(progress.labels.length);

Upload-Fortschritt 1

Beschriftung mit Prozentwert aktualisieren

// HTML:
// <label for="dl">Download: 0 %</label>
// <progress id="dl" max="100" value="0"></progress>

const bar = document.getElementById('dl');

const setProgress = (value) => {
  bar.value = value;
  const percent = Math.round((bar.value / bar.max) * 100);
  bar.labels.forEach((label) => {
    label.textContent = `Download: ${percent} %`;
  });
};

setProgress(42);
console.log(bar.labels[0].textContent);

Download: 42 %

Fortschrittsbalken ohne Beschriftung finden (Barrierefreiheit)

const unlabeled = [...document.querySelectorAll('progress')]
  .filter((p) => p.labels.length === 0
    && !p.hasAttribute('aria-label')
    && !p.hasAttribute('aria-labelledby'));

unlabeled.forEach((p) => {
  console.warn('Progress ohne Label:', p.id || p);
});

Progress ohne Label: sync (falls ein solches Element existiert)

Live-Verhalten der NodeList

const p = document.createElement('progress');
p.id = 'job';
document.body.append(p);

const labels = p.labels;
console.log(labels.length);

const label = document.createElement('label');
label.htmlFor = 'job';
label.textContent = 'Auftrag';
document.body.prepend(label);

console.log(labels.length); // dieselbe Liste, jetzt aktualisiert

0 1

// Wichtig · Fallstricke

Kein null: Ohne Labels liefert die Eigenschaft eine leere NodeList. Prüfe also labels.length und nicht auf null.
Live-Liste: Wenn du in einer Schleife Labels aus dem DOM entfernst, ändert sich die Liste noch während der Schleife. Kopiere sie vorher mit [...progress.labels].
Verschachtelte Labels: Ein umschließendes <label> gilt nur dann als zugeordnet, wenn das <progress> das erste beschriftbare Element darin ist und das Label kein abweichendes for-Attribut hat.
ARIA zählt nicht: Beschriftungen über aria-label oder aria-labelledby tauchen in labels nicht auf.
Browser-Unterstützung: Chrome, Edge und Safari unterstützen die Eigenschaft seit Langem, Firefox erst ab Version 56. Sehr alte Browser liefern undefined. Als Ausweichlösung eignet sich document.querySelectorAll(`label[for=\"${CSS.escape(id)}\"]`).

Siehe auch

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