Signatur
Beschreibung
Die Eigenschaft label des HTMLTrackElement spiegelt das HTML-Attribut label eines <track>-Elements. Sie enthält einen für Menschen lesbaren Titel wie "Deutsch", "English (CC)" oder "Audiodeskription". Browser zeigen diesen Titel an, wenn sie im Medienplayer die verfügbaren Untertitel, Beschreibungen oder Kapitel auflisten.
Die Eigenschaft ist lesbar und schreibbar. Wenn Sie ihr einen Wert zuweisen, wird das Attribut label im DOM aktualisiert. Fehlt das Attribut, gibt die Eigenschaft einen leeren String "" zurück, nicht null.
Gebraucht wird label vor allem für eigene Player-Oberflächen, etwa wenn Sie die nativen Steuerelemente ausblenden und ein eigenes Untertitelmenü bauen. Außerdem können Sie damit Beschriftungen nachträglich lokalisieren. Zum selben Track gehört ein TextTrack-Objekt, das Sie über trackElement.track erreichen. Dessen Eigenschaft TextTrack.label ist schreibgeschützt und übernimmt den Wert vom Element.
Innerhalb eines Medienelements sollte jeder Track mit gleichem kind ein eindeutiges Label haben. Sonst können Benutzer die Einträge im Menü nicht auseinanderhalten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "" | Nur beim Setzen: der neue lesbare Titel des Tracks. Andere Werte werden in einen String umgewandelt. |
Rückgabewert
label oder ein leerer String "", wenn das Attribut fehlt.Beispiele
Label eines Tracks auslesen
// HTML:
// <video id="film" src="film.mp4" controls>
// <track kind="subtitles" src="de.vtt" srclang="de" label="Deutsch" default>
// <track kind="subtitles" src="en.vtt" srclang="en">
// </video>
const tracks = document.querySelectorAll('#film track');
tracks.forEach((track) => {
console.log(`${track.srclang}: "${track.label}"`);
});Label nachträglich setzen und lokalisieren
const labels = { de: 'Deutsch', en: 'Englisch', fr: 'Französisch' };
document.querySelectorAll('video track[kind="subtitles"]').forEach((track) => {
// Fehlende Labels anhand der Sprache ergänzen
if (!track.label) {
track.label = labels[track.srclang] ?? track.srclang.toUpperCase();
}
});
const enTrack = document.querySelector('track[srclang="en"]');
console.log(enTrack.label);
console.log(enTrack.getAttribute('label'));Eigenes Untertitelmenü aus den Labels erzeugen
const video = document.querySelector('#film');
const menu = document.querySelector('#untertitel-menu'); // <select>
const trackElements = [...video.querySelectorAll('track')]
.filter((t) => t.kind === 'subtitles' || t.kind === 'captions');
menu.append(new Option('Aus', ''));
trackElements.forEach((el, index) => {
// Label als sichtbaren Text, Fallback auf die Sprache
const text = el.label || el.srclang || `Spur ${index + 1}`;
menu.append(new Option(text, String(index)));
});
menu.addEventListener('change', () => {
trackElements.forEach((el, index) => {
el.track.mode = String(index) === menu.value ? 'showing' : 'disabled';
});
});// Wichtig · Fallstricke
- Leerer String statt
null: Fehlt das Attribut, liefertlabelden Wert"". Prüfen Sie deshalb mitif (!track.label)und nicht mit=== null. - Ohne Label wählt der Browser selbst eine Beschriftung: Ist kein Label gesetzt, zeigen Browser im nativen Menü oft nur die Sprache oder einen allgemeinen Text wie „Unbekannt“. Das ist nicht einheitlich. Für eine gute Barrierefreiheit sollten Sie immer ein aussagekräftiges Label angeben.
TextTrack.labelist schreibgeschützt: Ändern Sie das Label über dasHTMLTrackElement, nicht übertrackElement.track.label. Ob ein bereits geöffnetes natives Menü die Änderung sofort anzeigt, unterscheidet sich je nach Browser.- Sicherheit: Labels können aus Benutzereingaben oder externen Daten stammen. Schreiben Sie sie in eigene Oberflächen nur über
textContentodernew Option(), nicht überinnerHTML. So verhindern Sie XSS-Angriffe. - Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. Der Internet Explorer unterstützt sie ab Version 10.