VTTCue.position — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.position

Beschreibung

Die Eigenschaft position des Interfaces VTTCue legt fest, wo die Box des Untertitels innerhalb der Zeile steht. Bei horizontaler Schreibrichtung (Standard) ist das die waagerechte Position als Prozentwert der Videobreite. Bei vertikalem Text (vertical = "rl" oder "lr") ist es die senkrechte Position als Prozentwert der Videohöhe.

Der Wert ist entweder eine Zahl zwischen 0 und 100 oder der String "auto". Bei "auto" berechnet der Browser die Position anhand von align: Bei "left" oder "start" (in LTR) liegt sie bei 0 %, bei "center" bei 50 %, bei "right" oder "end" bei 100 %. Welcher Teil der Box an diesem Punkt verankert wird, bestimmt positionAlign (Anfang, Mitte oder Ende).

Die Eigenschaft entspricht der Einstellung position: in einer WebVTT-Datei (z. B. position:10%). Man nutzt sie vor allem, um Untertitel seitlich zu verschieben, etwa damit sie wichtige Bildinhalte nicht verdecken oder um bei Dialogen die Sprecher zu kennzeichnen. Zusammen mit line (senkrechte Lage) und size (Breite der Box) lässt sich die Box frei im Video platzieren.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	number \| "auto"	"auto"	Neue Position als Prozentwert zwischen `0` und `100` oder `"auto"` für eine automatische Berechnung anhand von `align`.

Rückgabewert

Typ

number | "auto"

Beschreibung

Die aktuelle Einrückung als Zahl (Prozent, 0–100) oder der String "auto", wenn keine feste Position gesetzt ist.

Beispiele

Untertitel an den linken Rand setzen

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

const cue = new VTTCue(2, 6, 'Sprecher A: Hallo!');
console.log(cue.position); // Standardwert

cue.position = 10;          // 10 % vom linken Rand
cue.positionAlign = 'line-left';
cue.size = 40;              // Box ist 40 % breit
track.addCue(cue);

console.log(cue.position);

auto 10

Dialog: Sprecher links und rechts darstellen

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

const dialog = [
  { start: 0, end: 3, text: 'Wo warst du?', side: 'left' },
  { start: 3, end: 6, text: 'Im Büro.', side: 'right' }
];

for (const { start, end, text, side } of dialog) {
  const cue = new VTTCue(start, end, text);
  cue.size = 35;
  cue.position = side === 'left' ? 5 : 95;
  cue.positionAlign = side === 'left' ? 'line-left' : 'line-right';
  track.addCue(cue);
}

console.log([...track.cues].map((c) => c.position));

[5, 95]

Ungültige Werte abfangen und Position zurücksetzen

const cue = new VTTCue(0, 5, 'Test');

try {
  cue.position = 150; // außerhalb von 0–100
} catch (err) {
  console.log(err.name);
}

cue.position = 50;
cue.position = 'auto'; // zurück zur automatischen Berechnung
console.log(cue.position);

IndexSizeError auto

Position aus einer WebVTT-Datei auslesen

// untertitel.vtt enthält z. B.:
// 00:00:01.000 --> 00:00:04.000 position:20% align:start
// Text oben links
const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  const [first] = trackEl.track.cues;
  console.log(first.position, first.align);
});
trackEl.track.mode = 'hidden'; // Cues laden, ohne sie anzuzeigen

20 start

// Wichtig · Fallstricke

Bei Werten außerhalb von 0–100 wirft der Setter eine DOMException vom Typ IndexSizeError. Andere Strings als "auto" werden je nach Browser still ignoriert oder lösen einen TypeError aus.
Die Bedeutung hängt von vertical ab: Bei vertikalem Text steuert position die senkrechte Lage, nicht die waagerechte.
Ohne passendes positionAlign und size kann die Box über den Videorand hinausragen. Der Browser verschiebt oder kürzt sie dann selbst, deshalb wirkt z. B. position = 95 mit zentrierter Ausrichtung oft anders als erwartet.
Der Wert beschreibt nur die gewünschte Lage. Wie der Browser die Untertitel tatsächlich zeichnet (Kollisionen vermeiden, Schriftgröße), unterscheidet sich teilweise zwischen den Engines. Ältere Versionen von Chrome und Safari unterstützten "auto" nicht oder nur eingeschränkt.
Die Änderung ist nur sichtbar, wenn der Track im Modus mode = "showing" ist.

Siehe auch

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