VTTCue.getCueAsHTML() — Methode · JavaScript-Referenz

Signatur

VTTCue.prototype.getCueAsHTML()

Beschreibung

Die Methode getCueAsHTML() liest die Eigenschaft text eines VTTCue ein, verarbeitet sie nach den Regeln für WebVTT-Cue-Text und gibt das Ergebnis als DocumentFragment zurück. WebVTT-Auszeichnungen werden dabei in passende HTML-Knoten übersetzt:

, , , <ruby> und <rt> werden zu den gleichnamigen HTML-Elementen.
<c.klasse> wird zu .
<v Sprecher> wird zu .
<lang de> wird zu .
Zeitstempel innerhalb des Cues (<00:00:05.000>) werden zu ProcessingInstruction-Knoten mit dem Ziel timestamp.

Die Methode wird vor allem dann gebraucht, wenn Sie Untertitel nicht vom Browser zeichnen lassen, sondern in einem eigenen Overlay darstellen möchten – etwa für einen eigenen Videoplayer mit individuellem Design. Dazu setzen Sie den Modus der Textspur auf "hidden", lauschen auf das Ereignis cuechange und hängen für jeden aktiven Cue das Fragment in Ihren Container ein.

Da nur die in WebVTT erlaubten Auszeichnungen erzeugt werden und unbekannte Tags verworfen werden, ist das Ergebnis deutlich sicherer als ein direktes Setzen von cue.text per innerHTML.

Rückgabewert

Typ

DocumentFragment

Beschreibung

Ein neues DocumentFragment mit Text-, Element- und ggf. ProcessingInstruction-Knoten, die den Inhalt des Cues abbilden. Bei jedem Aufruf wird ein neues Fragment erzeugt.

Beispiele

Cue-Text in HTML umwandeln und untersuchen

const cue = new VTTCue(0, 4, '<v Anna>Hallo <b>Welt</b>!</v> <c.hinweis>(lacht)</c>');

const fragment = cue.getCueAsHTML();
const wrapper = document.createElement('div');
wrapper.append(fragment);

console.log(wrapper.innerHTML);

Hallo Welt! (lacht)

Eigenes Untertitel-Overlay für einen Videoplayer

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

// Browser-Darstellung ausblenden, Cues aber weiterhin aktiv halten
track.mode = 'hidden';

track.addEventListener('cuechange', () => {
  overlay.replaceChildren();
  for (const cue of track.activeCues ?? []) {
    const zeile = document.createElement('p');
    zeile.append(cue.getCueAsHTML());
    overlay.append(zeile);
  }
});

Sprecher aus einem Cue auslesen

const cue = new VTTCue(10, 14, '<v Moderator>Willkommen zur Sendung.</v>');

const sprecher = [...cue.getCueAsHTML().querySelectorAll('span[title]')]
  .map((span) => span.title);

console.log(sprecher);

["Moderator"]

// Wichtig · Fallstricke

Einmalig verwendbar: Hängen Sie das Fragment ins DOM ein, wird es dabei geleert. Wollen Sie den Inhalt öfter nutzen, rufen Sie die Methode erneut auf oder klonen Sie die Knoten mit cloneNode(true).
Keine Stile: Regeln mit ::cue und Cue-Einstellungen wie line, position oder align gelten für das Fragment nicht. Beim eigenen Rendern müssen Sie Positionierung und Aussehen selbst per CSS umsetzen, z. B. über die erzeugten Klassen.
Zeitstempel: Karaoke-Zeitstempel landen als ProcessingInstruction-Knoten im Fragment. Im HTML-DOM werden sie nicht angezeigt, beim Durchlaufen der Knoten sollten Sie sie aber berücksichtigen.
Sicherheit: Die Methode erzeugt nur Elemente, die WebVTT erlaubt. Skripte oder Ereignis-Attribute entstehen dabei nicht. Wer cue.text stattdessen per innerHTML einfügt, öffnet bei fremden Untertiteldateien eine XSS-Lücke.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere Versionen von Edge (EdgeHTML) und dem Internet Explorer kennen nur TextTrackCue ohne diese Methode.

Siehe auch

VTTCue VTTCue.text TextTrack.activeCues DocumentFragment TextTrack.mode SyncManager.register()