VTTCue.snapToLines — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.snapToLines

Beschreibung

Die Eigenschaft snapToLines der Schnittstelle VTTCue bestimmt, wie der Wert von VTTCue.line ausgewertet wird. Ist sie true (Standard), gibt line eine Zeilennummer an: positive Werte zählen von oben (0 = erste Zeile), negative Werte von unten (-1 = letzte Zeile). Die Höhe einer Zeile ergibt sich aus der Schriftgröße des Untertitels.

Ist snapToLines false, wird line als Prozentwert (0–100) der Videohöhe gelesen (bei vertikalem Text: der Videobreite). So lässt sich ein Untertitel pixelunabhängig und genau platzieren, etwa bei 10 % vom oberen Rand.

Die Eigenschaft entspricht in einer WebVTT-Datei der Cue-Einstellung line:: line:-2 ergibt snapToLines = true, line:80% dagegen snapToLines = false. Mit „Snap“ ist auch gemeint, dass der Browser bei true Cues so verschieben darf, dass sie sich nicht überlappen und im sichtbaren Bereich bleiben.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn line eine Zeilennummer ist (Standardwert), false, wenn line einen Prozentwert angibt. Die Eigenschaft ist beschreibbar.

Beispiele

Untertitel in der vorletzten Zeile anzeigen

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

const cue = new VTTCue(0, 5, 'Hallo und willkommen!');
cue.snapToLines = true; // Standard: line = Zeilennummer
cue.line = -2;          // zweite Zeile von unten
track.addCue(cue);

console.log(cue.snapToLines, cue.line);

true -2

Cue prozentual oben im Bild positionieren

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

const cue = new VTTCue(2, 8, '[Musik setzt ein]');
cue.snapToLines = false; // line = Prozent der Videohöhe
cue.line = 10;           // 10 % vom oberen Rand
cue.lineAlign = 'start';
track.addCue(cue);

console.log(`${cue.line} %`);

10 %

Positionierungsart vorhandener Cues auswerten

const video = document.querySelector('video');
const [track] = video.textTracks;
track.mode = 'hidden'; // Cues laden, aber nicht anzeigen

video.addEventListener('loadedmetadata', () => {
  for (const cue of track.cues ?? []) {
    if (!(cue instanceof VTTCue)) continue;
    const art = cue.snapToLines ? 'Zeile' : 'Prozent';
    console.log(`${cue.text}: line=${cue.line} (${art})`);
  }
});

Hallo Welt: line=auto (Zeile) Oben: line=10 (Prozent)

// Wichtig · Fallstricke

Reihenfolge egal, Bedeutung nicht: Wer line = 90 setzt, aber snapToLines auf true lässt, bekommt „Zeile 90“. Der Cue landet dann meist am unteren Rand statt bei 90 %. Setze snapToLines = false immer ausdrücklich, wenn du Prozentwerte verwendest.
Ist line \"auto\", hat snapToLines kaum Wirkung. Der Browser platziert den Cue dann selbst.
Bei snapToLines = false verschiebt der Browser überlappende Cues nicht automatisch. Mehrere Cues zur selben Zeit können sich dann überdecken.
Die Darstellung unterscheidet sich zwischen Browsern (vor allem ältere Safari-Versionen und benutzerdefinierte Player-Oberflächen). Wenn Positionen wichtig sind, teste sie in mehreren Browsern.
Die Eigenschaft wirkt sich nur auf die Anzeige aus, wenn die Spur den Modus showing hat.

Siehe auch

VTTCue VTTCue.line VTTCue.position VTTCue.vertical TextTrack.addCue() HTMLMediaElement.addTextTrack()