Signatur
Beschreibung
Die Eigenschaft lineAlign eines VTTCue-Objekts legt fest, wie die Cue-Box an ihrer Zeilenposition verankert wird. Die Zeilenposition selbst setzt man über VTTCue.line. Bei horizontalem Text ist das die vertikale Position der Untertitel im Video. lineAlign bestimmt dann, ob die Oberkante ("start"), die Mitte ("center") oder die Unterkante ("end") der Box auf dieser Position liegt.
Mögliche Werte (Typ LineAlignSetting):
"start": Der Anfang der Box liegt auf der Zeilenposition. Das ist der Standardwert."center": Die Box ist mittig auf der Zeilenposition ausgerichtet."end": Das Ende der Box liegt auf der Zeilenposition.
In einer WebVTT-Datei entspricht das dem zweiten Teil der line-Einstellung, z. B. line:50%,center. Die Eigenschaft wirkt sich vor allem dann sichtbar aus, wenn line ein Prozentwert ist, also snapToLines auf false steht. Damit lassen sich Untertitel gezielt positionieren, z. B. genau in der Bildmitte oder bündig am unteren Rand.
Bei vertikalem Text (vertical = "rl" oder "lr") gilt die Ausrichtung entsprechend auf der horizontalen Achse.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | "start" | "center" | "end" | "start" | Neuer Wert beim Setzen der Eigenschaft. Andere Zeichenketten werden stillschweigend ignoriert: Es gibt keinen Fehler, und der alte Wert bleibt erhalten. |
Rückgabewert
Beispiele
Untertitel genau in der Bildmitte zentrieren
const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';
const cue = new VTTCue(2, 6, 'Achtung – wichtiger Hinweis!');
cue.snapToLines = false; // line als Prozentwert verwenden
cue.line = 50; // 50 % der Videohöhe
cue.lineAlign = 'center'; // Mitte der Box liegt auf 50 %
track.addCue(cue);
console.log(cue.lineAlign);Cue bündig am unteren Rand verankern
const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Untertitel', 'de');
track.mode = 'showing';
const cue = new VTTCue(0, 4, 'Unterkante liegt bei 90 %');
cue.snapToLines = false;
cue.line = 90;
cue.lineAlign = 'end'; // Box wächst nach oben, statt über den Rand zu ragen
track.addCue(cue);
console.log(`${cue.line}% / ${cue.lineAlign}`);Ungültige Werte werden ignoriert
const cue = new VTTCue(0, 3, 'Test');
console.log(cue.lineAlign); // Standardwert
cue.lineAlign = 'middle'; // kein gültiger Wert
console.log(cue.lineAlign);
cue.lineAlign = 'end';
console.log(cue.lineAlign);Ausrichtung aus einer geladenen WebVTT-Datei auslesen
// Datei enthält z. B.: 00:00.000 --> 00:03.000 line:20%,center
const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
for (const cue of trackEl.track.cues) {
if (cue instanceof VTTCue) {
console.log(cue.text, '→', cue.line, cue.lineAlign);
}
}
});
trackEl.track.mode = 'hidden'; // Cues laden, ohne sie anzuzeigen// Wichtig · Fallstricke
- Browser-Unterstützung:
lineAlignwird nicht überall unterstützt. Firefox setzt die Eigenschaft um, Chromium-basierte Browser und Safari nur eingeschränkt oder gar nicht. Dort kann die Eigenschaft fehlen (undefined) oder keine sichtbare Wirkung haben. Vor dem Einsatz sollte man die Unterstützung prüfen, z. B. mit'lineAlign' in VTTCue.prototype. - Nur mit
snapToLines = falserelevant: Wennlineein Zeilenindex ist (snapToLines = true) oderline = "auto"gilt, berücksichtigt der Layout-AlgorithmuslineAlignin der Regel nicht. - Nicht verwechseln mit
align(Ausrichtung des Textes innerhalb der Box) undpositionAlign(Verankerung entlang der Textrichtung, also horizontal bei normalem Text). - Ungültige Werte lösen keinen Fehler aus, sondern werden ignoriert. Das kann Tippfehler wie
"middle"verschleiern. - Browser-eigene Stile oder
::cue-CSS können die Darstellung zusätzlich beeinflussen, das Positionsmodell selbst ändern sie aber nicht.