VTTCue.positionAlign — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.positionAlign

Beschreibung

Die Eigenschaft positionAlign eines VTTCue-Objekts bestimmt, welcher Punkt der Cue-Box auf der Position liegt, die position angibt. position ist ein Prozentwert entlang der Zeilenrichtung (bei horizontalem Text also von links nach rechts). Ob dieser Wert den linken Rand, die Mitte oder den rechten Rand der Box beschreibt, entscheidet positionAlign.

Mögliche Werte sind:

"line-left" – Die Position gibt den linken Rand der Box an (bezogen auf die Zeilenrichtung). Die Box wächst von dort aus nach rechts.
"center" – Die Position gibt die Mitte der Box an.
"line-right" – Die Position gibt den rechten Rand der Box an. Die Box wächst von dort aus nach links.
"auto" (Standard) – Die Ausrichtung ergibt sich aus VTTCue.align: "left" ergibt line-left, "right" ergibt line-right, "center" ergibt center. "start" und "end" hängen von der Schreibrichtung des Textes ab.

In einer WebVTT-Datei entspricht die Eigenschaft dem Zusatz nach dem Komma in der Cue-Einstellung position, zum Beispiel position:10%,line-left. Du brauchst sie vor allem dann, wenn du Untertitel gezielt platzieren willst, etwa neben einer sprechenden Person oder so, dass sie Bildinhalte nicht verdecken. Zusammen mit size (Breite der Box) und line (senkrechte Position) ergibt sich die vollständige Geometrie der Cue-Box.

Parameter

Name	Typ	Default	Beschreibung
$wert	"line-left" \| "center" \| "line-right" \| "auto"	"auto"	Neuer Wert beim Setzen der Eigenschaft. Ungültige Zeichenketten werden ohne Fehlermeldung ignoriert, der bisherige Wert bleibt dann erhalten.

Rückgabewert

Typ

string

Beschreibung

Einer der Werte "line-left", "center", "line-right" oder "auto".

Beispiele

Cue am linken Bildrand verankern

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

const cue = new VTTCue(1, 5, 'Sprecherin links im Bild');
cue.position = 10;            // 10 % vom linken Rand
cue.positionAlign = 'line-left'; // linker Rand der Box liegt bei 10 %
cue.size = 40;                // Box ist 40 % breit
cue.align = 'start';

track.addCue(cue);
console.log(cue.positionAlign);

line-left

Untertitel rechtsbündig am rechten Rand platzieren

const cue = new VTTCue(6, 9, 'Antwort von rechts');
cue.position = 90;               // rechter Rand der Box bei 90 %
cue.positionAlign = 'line-right';
cue.size = 35;
cue.align = 'right';

// Ungültige Werte werden stillschweigend ignoriert
cue.positionAlign = 'rechts';
console.log(cue.positionAlign);

line-right

Wert aus einer WebVTT-Datei auslesen

// untertitel.vtt enthält z. B.:
// 00:00:01.000 --> 00:00:04.000 position:50%,center size:60%
// Zentrierter Hinweistext

const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  for (const cue of trackEl.track.cues) {
    console.log(`${cue.startTime}s: position=${cue.position}, positionAlign=${cue.positionAlign}`);
  }
});

1s: position=50, positionAlign=center

Funktionsprüfung vor der Verwendung

const supportsPositionAlign =
  typeof VTTCue !== 'undefined' && 'positionAlign' in VTTCue.prototype;

const cue = new VTTCue(0, 3, 'Hallo');
if (supportsPositionAlign) {
  cue.positionAlign = 'center';
} else {
  // Ausweichlösung: Box selbst über position und size mittig ausrichten
  cue.size = 50;
  cue.position = 25;
}
console.log(supportsPositionAlign);

true (bzw. false in Browsern ohne Unterstützung)

// Wichtig · Fallstricke

Browser-Unterstützung: Nicht alle Browser unterstützen die Eigenschaft. Firefox setzt sie um, Chromium-basierte Browser haben sie bisher nicht vollständig implementiert. Prüfe vorher mit 'positionAlign' in VTTCue.prototype, ob sie verfügbar ist, und sieh dir die Darstellung in allen Zielbrowsern an.
Veraltete Werte: Frühere Entwürfe der Spezifikation und alte Browser-Versionen verwendeten "start", "middle" und "end". Heute gelten ausschließlich "line-left", "center", "line-right" und "auto".
Stilles Ignorieren: Tippfehler wie "left" statt "line-left" lösen keinen Fehler aus, der Wert wird einfach nicht übernommen. Lies die Eigenschaft nach dem Setzen zur Kontrolle aus.
Nicht verwechseln mit align: positionAlign verankert die Box, align richtet den Text innerhalb der Box aus. Bei "auto" wird die Verankerung aus align abgeleitet.
Bei vertikalem Text (vertical = "rl" oder "lr") bezieht sich die Zeilenrichtung auf die senkrechte Achse. line-left bedeutet dann oben.
Die Eigenschaft wirkt sich nur aus, wenn position einen Zahlenwert hat. Steht position auf "auto", hängt das Ergebnis zusätzlich von align ab.

Siehe auch

VTTCue VTTCue.position VTTCue.align VTTCue.size VTTCue.line VTTCue.vertical TextTrack.addCue()