TextTrackCueList.length — Eigenschaft · JavaScript-Referenz

Signatur

TextTrackCueList.length

Beschreibung

TextTrackCueList.length liefert eine nicht negative Ganzzahl. Sie gibt an, wie viele TextTrackCue-Objekte (meist VTTCue) die Liste gerade enthält. Solche Listen erhält man über TextTrack.cues (alle Cues einer Spur) oder TextTrack.activeCues (Cues, die zum aktuellen Wiedergabezeitpunkt aktiv sind).

Die Eigenschaft braucht man vor allem, um mit einer klassischen for-Schleife über die Liste zu gehen, da TextTrackCueList kein echtes Array ist. Außerdem lässt sich damit schnell prüfen, ob eine Spur schon geladen ist oder ob gerade ein Untertitel angezeigt wird (activeCues.length > 0).

Die Liste ist live: Fügt man mit TextTrack.addCue() Cues hinzu oder entfernt man sie mit removeCue(), ändert sich length sofort. Bei activeCues schwankt der Wert während der Wiedergabe laufend.

Rückgabewert

Typ

number

Beschreibung

Anzahl der Cues in der Liste als nicht negative Ganzzahl (unsigned long).

Beispiele

Alle Cues einer Untertitelspur auflisten

const video = document.querySelector('video');
const track = video.textTracks[0];

// Ohne mode 'hidden' oder 'showing' werden die Cues nicht geladen
track.mode = 'hidden';

video.querySelector('track').addEventListener('load', () => {
  const { cues } = track;
  console.log(`Anzahl Cues: ${cues.length}`);
  for (let i = 0; i < cues.length; i++) {
    console.log(`${cues[i].startTime}s: ${cues[i].text}`);
  }
});

Anzahl Cues: 3 0s: Hallo! 2.5s: Willkommen zum Video. 5s: Los geht's.

Prüfen, ob gerade ein Untertitel aktiv ist

const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'hidden';

track.addEventListener('cuechange', () => {
  const active = track.activeCues;
  const box = document.querySelector('#untertitel');
  box.textContent = active.length > 0
    ? Array.from({ length: active.length }, (_, i) => active[i].text).join('\n')
    : '';
});

length ändert sich live nach addCue()

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Deutsch', 'de');
track.mode = 'showing';

const cues = track.cues;
console.log(cues.length);

track.addCue(new VTTCue(0, 2, 'Erster Untertitel'));
track.addCue(new VTTCue(2, 4, 'Zweiter Untertitel'));
console.log(cues.length);

track.removeCue(cues[0]);
console.log(cues.length);

0 2 1

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an length wird ignoriert (im Strict Mode gibt es einen TypeError). Die Liste ändert man nur über addCue() und removeCue().
null statt Liste: Steht TextTrack.mode auf "disabled", sind track.cues und track.activeCues null. Ein direkter Zugriff auf .length wirft dann einen Fehler. Deshalb vorher den Modus setzen oder Optional Chaining nutzen: track.cues?.length ?? 0.
Asynchrones Laden: Bei <track>-Elementen ist length so lange 0, bis die WebVTT-Datei geladen ist. Warten Sie auf das load-Ereignis des <track>-Elements.
Live-Liste: Wenn Sie in einer Schleife Cues entfernen, ändert sich length während der Schleife. Entfernen Sie deshalb rückwärts oder kopieren Sie die Liste vorher mit Array.from().
Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

DataTransferItemList.length TextTrackList.length AudioTrackList.length ImageTrackList.length VideoTrackList.length