</> programmierung.net
Start · Sprachen · JavaScript · Referenz · VTTCue.align

VTTCue.align

Eigenschaft

Liest oder setzt die Textausrichtung aller Zeilen innerhalb des Untertitel-Kastens eines <code>VTTCue</code>, z. B. <code>"start"</code>, <code>"center"</code> oder <code>"end"</code>.

seit JavaScript Baseline: alle modernen Browser Kategorie: webapi

Signatur

VTTCue.align

Beschreibung

Die Eigenschaft align der Schnittstelle VTTCue legt fest, wie die Textzeilen eines Untertitels bzw. einer Beschriftung innerhalb ihres Kastens ausgerichtet werden. Sie entspricht der WebVTT-Einstellung align: in einer .vtt-Datei, z. B. 00:00:01.000 --> 00:00:04.000 align:start.

Der Wert ist eine Zeichenkette vom Typ AlignSetting. Erlaubt sind:

  • "start": Ausrichtung am Zeilenanfang, abhängig von der Schreibrichtung (bei Links-nach-rechts-Text also links, bei Arabisch oder Hebräisch rechts).
  • "center": zentriert (Standardwert).
  • "end": Ausrichtung am Zeilenende, ebenfalls abhängig von der Schreibrichtung.
  • "left": immer links, unabhängig von der Schreibrichtung.
  • "right": immer rechts, unabhängig von der Schreibrichtung.

Die Eigenschaft ist lesend und schreibend. Du kannst sie zum Beispiel nutzen, wenn du Untertitel per JavaScript erzeugst (new VTTCue() plus TextTrack.addCue()) oder wenn du die Ausrichtung vorhandener Untertitel zur Laufzeit änderst, etwa für eine Einstellung wie „Untertitel linksbündig“. align betrifft nur die Ausrichtung des Textes innerhalb des Kastens. Wo der Kasten selbst sitzt, bestimmen position, positionAlign, line und size.

Parameter

Name Typ Default Beschreibung
$value "start" | "center" | "end" | "left" | "right" "center" Neuer Ausrichtungswert beim Setzen. Ungültige Werte werden ohne Fehler ignoriert.

Rückgabewert

Typ
string
Beschreibung
Die aktuelle Ausrichtung als AlignSetting-Zeichenkette: "start", "center", "end", "left" oder "right".

Beispiele

Untertitel per JavaScript erzeugen und linksbündig ausrichten

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

const cue = new VTTCue(1, 4, 'Hallo und willkommen!\nHeute geht es um WebVTT.');
console.log(cue.align); // Standardwert

cue.align = 'start';
track.addCue(cue);
console.log(cue.align);
center start

Ausrichtung aller Untertitel per Benutzereinstellung umschalten

const video = document.querySelector('video');
const select = document.querySelector('#caption-align'); // <select> mit start/center/end

const applyAlign = (value) => {
  for (const track of video.textTracks) {
    if (!track.cues) continue; // cues ist null, solange mode === 'disabled'
    for (const cue of track.cues) {
      if (cue instanceof VTTCue) cue.align = value;
    }
  }
};

select.addEventListener('change', (e) => applyAlign(e.target.value));

Ungültige Werte werden stillschweigend ignoriert

const cue = new VTTCue(0, 2, 'Test');
cue.align = 'right';
cue.align = 'middle'; // veralteter Wert, heute ungültig
cue.align = 'links';  // ungültig
console.log(cue.align);
right

Ausrichtung aus einer .vtt-Datei auslesen

// untertitel.vtt:
// WEBVTT
//
// 00:00:01.000 --> 00:00:04.000 align:end
// Rechtsbündiger Text

const trackEl = document.querySelector('track');
trackEl.track.mode = 'hidden';
trackEl.addEventListener('load', () => {
  const [first] = trackEl.track.cues;
  console.log(first.align);
});
end

// Wichtig · Fallstricke

  • Kein Fehler bei ungültigen Werten: Setzt du einen Wert außerhalb von AlignSetting, wird die Zuweisung ohne Fehlermeldung ignoriert, und der alte Wert bleibt erhalten. Tippfehler fallen dadurch leicht nicht auf.
  • Veralteter Wert "middle": Ältere Entwürfe der Spezifikation und alte Browser-Versionen nutzten "middle" statt "center". Heute gilt nur noch "center".
  • start/end vs. left/right: start und end richten sich nach der Schreibrichtung des Textes. Für mehrsprachige Untertitel sind sie meist die bessere Wahl als die festen Werte left und right.
  • Zusammenspiel mit anderen Eigenschaften: Wenn positionAlign auf "auto" steht, leitet der Browser die Ausrichtung des Kastens aus align ab. Das kann die Position des Untertitels verschieben.
  • cues kann null sein: Solange TextTrack.mode auf "disabled" steht, ist track.cues null. Setze den Modus vorher auf "hidden" oder "showing".
  • Browser-Unterstützung: Die Eigenschaft wird von allen aktuellen Browsern unterstützt. Wie genau die Untertitel dargestellt werden, unterscheidet sich aber je nach Browser. Nutzereinstellungen für Untertitel auf Betriebssystemebene können die Darstellung zusätzlich überschreiben.

Siehe auch

VTTCue VTTCue.position VTTCue.line VTTCue.size TextTrack
← Vorheriger Eintrag VTTCue