HTMLOutputElement.labels — Eigenschaft · JavaScript-Referenz

Signatur

HTMLOutputElement.labels

Beschreibung

Die Eigenschaft labels eines HTMLOutputElement gibt eine NodeList zurück. Darin stehen alle <label>-Elemente, die zum jeweiligen <output> gehören. Ein Label ist mit dem Element verknüpft, wenn sein for-Attribut auf die id des <output> verweist oder wenn das <output> direkt im Label verschachtelt ist.

<output> ist ein beschriftbares Formularelement (labelable element). Deshalb kann man ihm eine sichtbare Beschriftung zuordnen, die auch Screenreader als zugänglichen Namen vorlesen. Mit labels kommt man per Skript an diese Beschriftungen heran, etwa um Einheiten anzuzeigen, Texte je nach Sprache auszutauschen oder Fehler- und Statuszustände hervorzuheben.

Die zurückgegebene NodeList ist live. Wird ein Label hinzugefügt, entfernt oder bekommt es ein anderes for-Attribut, ändert sich die Liste automatisch. Ist kein Label verknüpft, ist die Liste leer (length === 0), aber nie null.

Rückgabewert

Typ

NodeList

Beschreibung

Eine live aktualisierte NodeList mit HTMLLabelElement-Objekten in Dokumentreihenfolge. Ist kein Label verknüpft, ist sie leer.

Beispiele

Verknüpfte Labels auslesen

// HTML:
// <label for="ergebnis">Summe:</label>
// <output id="ergebnis">0</output>
// <label for="ergebnis">(in Euro)</label>

const output = document.getElementById('ergebnis');

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

2 Summe: (in Euro)

Rechner: Label je nach Ergebnis hervorheben

// HTML:
// <form id="rechner">
//   <input type="number" id="a" value="5"> +
//   <input type="number" id="b" value="3">
//   <label>Ergebnis: <output id="summe" for="a b"></output></label>
// </form>

const form = document.getElementById('rechner');
const summe = document.getElementById('summe');

const berechnen = () => {
  const wert = form.a.valueAsNumber + form.b.valueAsNumber;
  summe.value = Number.isNaN(wert) ? '–' : String(wert);

  // Alle zugehörigen Labels bei negativem Ergebnis markieren
  summe.labels.forEach((label) => {
    label.classList.toggle('negativ', wert < 0);
  });
};

form.addEventListener('input', berechnen);
berechnen();
console.log(summe.value, summe.labels[0].tagName);

8 LABEL

Live-Verhalten der NodeList

// HTML: <output id="status">bereit</output>
const status = document.getElementById('status');
const labels = status.labels;

console.log(labels.length); // noch kein Label

const label = document.createElement('label');
label.htmlFor = 'status';
label.textContent = 'Status:';
status.before(label);

// Dieselbe NodeList-Referenz ist schon aktualisiert
console.log(labels.length, labels[0].textContent);

0 1 Status:

// Wichtig · Fallstricke

Nicht verwechseln: Das for-Attribut von <output> (in JS output.htmlFor, eine DOMTokenList) nennt die Eingabefelder, aus denen das Ergebnis berechnet wird. Mit labels hat es nichts zu tun. Labels werden über das for-Attribut des Labels verknüpft.
Live-Liste: Wer beim Durchlaufen Labels entfernt oder umhängt, verändert die Liste während der Schleife. Dann vorher mit [...output.labels] eine statische Kopie anlegen.
Das for-Attribut eines Labels sucht nur im selben Baum. Ein Label im Hauptdokument erreicht also kein <output> in einem Shadow Root. Bei Elementen, die nicht im Dokument hängen, enthält die Liste nur Labels aus demselben losgelösten Teilbaum.
Die NodeList hat forEach, aber keine Array-Methoden wie map oder filter. Dafür vorher Array.from() verwenden.
Kompatibilität: Alle aktuellen Browser unterstützen die Eigenschaft. Firefox erst ab Version 56, der alte Internet Explorer gar nicht.

Siehe auch

HTMLButtonElement.labels HTMLOutputElement.name HTMLOutputElement.type HTMLOutputElement.value HTMLOutputElement.form