TextTrackCueList.getCueById() — Methode · JavaScript-Referenz

Signatur

TextTrackCueList.prototype.getCueById(id)

Beschreibung

Die Methode getCueById() durchsucht eine TextTrackCueList (zum Beispiel track.cues oder track.activeCues) nach der ersten Cue, deren Eigenschaft id genau mit dem übergebenen String übereinstimmt. In WebVTT-Dateien ist das die optionale Kennung, die in der Zeile direkt vor der Zeitangabe steht (z. B. intro vor 00:00.000 --> 00:04.000).

Nützlich ist die Methode, wenn du bestimmte Untertitel, Kapitel oder Metadaten-Cues gezielt ansprechen willst, ohne die ganze Liste per Schleife zu durchsuchen – etwa um zu einem benannten Kapitel zu springen, den Text einer Cue nachträglich zu ändern oder auf deren enter- und exit-Ereignisse zu reagieren.

Der Vergleich beachtet Groß- und Kleinschreibung. Kommen mehrere Cues mit derselben Kennung vor, wird nur die erste in Listenreihenfolge (also nach Startzeit sortiert) zurückgegeben. Bei einem leeren String liefert die Methode immer null, auch wenn es Cues ohne Kennung gibt.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die gesuchte Kennung der Cue. Wird mit `TextTrackCue.id` verglichen (exakt, Groß-/Kleinschreibung wird beachtet). Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

TextTrackCue | null

Beschreibung

Die erste passende Cue (in HTML-Videos meist eine VTTCue) oder null, wenn keine Cue diese Kennung hat oder id ein leerer String ist.

Beispiele

Zu einem benannten Kapitel springen

// WebVTT-Kapiteldatei enthält z. B.:
// fazit
// 05:10.000 --> 06:00.000
// Fazit und Ausblick
const video = document.querySelector('video');
const trackEl = document.querySelector('track[kind="chapters"]');

trackEl.addEventListener('load', () => {
  const cue = trackEl.track.cues.getCueById('fazit');
  if (cue) {
    console.log(`Kapitel "${cue.text}" beginnt bei ${cue.startTime} s`);
    video.currentTime = cue.startTime;
  }
});

// Spur aktivieren, damit sie geladen wird
trackEl.track.mode = 'hidden';

Kapitel "Fazit und Ausblick" beginnt bei 310 s

Selbst erzeugte Cue wiederfinden und ändern

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

const begruessung = new VTTCue(0, 3, 'Hallo!');
begruessung.id = 'gruss';
track.addCue(begruessung);
track.addCue(new VTTCue(3, 6, 'Willkommen im Video.'));

const gefunden = track.cues.getCueById('gruss');
gefunden.text = 'Hallo und herzlich willkommen!';
console.log(gefunden === begruessung);
console.log(track.cues.getCueById('Gruss'));

true null

Auf Betreten einer bestimmten Cue reagieren

const track = document.querySelector('track[kind="metadata"]').track;
track.mode = 'hidden';

const anmelden = () => {
  const cue = track.cues?.getCueById('werbung-1');
  if (!cue) return;
  cue.addEventListener('enter', () => console.log('Werbeblock startet'));
  cue.addEventListener('exit', () => console.log('Werbeblock endet'));
};

track.cues?.length ? anmelden() : track.addEventListener('cuechange', anmelden, { once: true });

Werbeblock startet Werbeblock endet

// Wichtig · Fallstricke

Spur muss aktiv sein: Ist track.mode gleich "disabled", ist track.cues null – ein Aufruf von getCueById() wirft dann einen TypeError. Setze den Modus auf "hidden" oder "showing" und nutze optional Chaining (track.cues?.getCueById(...)).
Ladezeitpunkt: Bei <track>-Elementen ist die Liste erst nach dem load-Ereignis des Elements gefüllt; vorher liefert die Methode null.
Eindeutigkeit: WebVTT erzwingt keine eindeutigen Kennungen. Bei doppelten IDs wird nur die erste Cue zurückgegeben.
Der Vergleich ist exakt und beachtet Groß- und Kleinschreibung; ein leerer String liefert immer null.
Auf track.activeCues angewendet, findet die Methode nur Cues, die gerade aktiv sind.
Wird in allen modernen Browsern unterstützt; der Internet Explorer hat nur eingeschränkte WebVTT-Unterstützung.

Siehe auch

VideoTrackList.getTrackById() TextTrackList.getTrackById() AudioTrackList.getTrackById() TextTrack.removeCue() TextTrack.addCue()