HTMLTrackElement.default — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTrackElement.default

Beschreibung

Die Eigenschaft default des HTMLTrackElement-Interfaces spiegelt das gleichnamige HTML-Attribut des <track>-Elements. Ist sie true, soll der Browser diese Textspur (Untertitel, Beschreibungen, Kapitel, Metadaten) aktivieren, wenn die Benutzereinstellungen keine andere Spur als passender ausweisen.

Je <video>- oder <audio>-Element darf pro Gruppe höchstens eine Spur als Standard markiert sein: höchstens eine Spur der Arten subtitles/captions, höchstens eine descriptions-Spur und höchstens eine chapters-Spur. Bei metadata-Spuren darf das Attribut beliebig oft gesetzt werden.

Wichtig: Das Attribut wirkt vor allem bei der ersten Auswahl der Spuren durch den Browser. Wer den Anzeigemodus später per Skript ändern will, sollte stattdessen track.track.mode ("showing", "hidden", "disabled") des zugehörigen TextTrack-Objekts setzen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Attribut default vorhanden ist, sonst false. Wird die Eigenschaft gesetzt, fügt der Browser das Attribut hinzu (true) oder entfernt es (false).

Beispiele

Standard-Untertitelspur 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" label="English">
// </video>

const tracks = document.querySelectorAll('#film track');
tracks.forEach((t) => {
  console.log(`${t.label}: default = ${t.default}`);
});

Deutsch: default = true English: default = false

Spur per Skript als Standard festlegen, bevor sie eingefügt wird

const video = document.querySelector('#film');

const track = document.createElement('track');
track.kind = 'captions';
track.src = 'captions-de.vtt';
track.srclang = 'de';
track.label = 'Deutsch (Hörgeschädigte)';
track.default = true; // setzt das HTML-Attribut "default"

video.append(track);
console.log(track.hasAttribute('default'));

true

Nutzerwahl berücksichtigen und Anzeige zuverlässig umschalten

const video = document.querySelector('#film');
const gewuenscht = navigator.language.startsWith('en') ? 'en' : 'de';

for (const el of video.querySelectorAll('track[kind="subtitles"]')) {
  const passt = el.srclang === gewuenscht;
  el.default = passt; // Attribut für die Markierung
  // mode bestimmt die tatsächliche Anzeige – auch nach dem Laden
  el.track.mode = passt ? 'showing' : 'disabled';
}

console.log([...video.textTracks].map((t) => `${t.language}:${t.mode}`));

["de:showing", "en:disabled"] (bei deutscher Browsersprache)

// Wichtig · Fallstricke

Nachträgliches Ändern wirkt oft nicht: Hat der Browser die Spuren schon ausgewählt, blendet ein Wechsel von default die Spur nicht mehr zuverlässig ein oder aus. Für Umschaltungen zur Laufzeit HTMLTrackElement.track.mode verwenden.
Stehen mehrere subtitles/captions-Spuren auf default, ist das ungültiges HTML. Browser nehmen dann in der Regel die erste Spur.
Benutzereinstellungen, z. B. die vom Betriebssystem bevorzugte Untertitelsprache in Safari, können Vorrang vor default haben.
WebVTT-Dateien von fremden Domains brauchen CORS und das Attribut crossorigin am Medienelement, sonst werden sie nicht geladen.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Internet Explorer unterstützt sie ab Version 10.

Siehe auch

HTMLInputElement.readOnly HTMLSourceElement.height HTMLTrackElement.label HTMLTrackElement.track HTMLTrackElement.kind