VTTCue.size — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.size

Beschreibung

Die Eigenschaft size eines VTTCue-Objekts legt fest, wie groß das Feld ist, in dem der Untertiteltext angezeigt wird. Der Wert ist ein Prozentwert zwischen 0 und 100. Er bezieht sich auf das Video-Anzeigefenster und entspricht der Cue-Einstellung size: in einer WebVTT-Datei, zum Beispiel 00:00:01.000 --> 00:00:04.000 size:50%.

Welche Richtung gemeint ist, hängt von vertical ab. Bei waagerechtem Text (vertical === "") gibt size die Breite des Felds an. Bei senkrechtem Text ("rl" oder "lr") gibt sie die Höhe an. Der Standardwert ist 100, das Feld nutzt also die volle Breite bzw. Höhe.

Man nutzt size vor allem zusammen mit position und positionAlign. So lassen sich Untertitel gezielt setzen, etwa schmale Textfelder für Sprecherzuordnung, Hinweise am Bildrand oder Untertitel, die ein Bildelement nicht verdecken sollen. Wenn sich size ändert, während der Cue angezeigt wird, zeichnet der Browser die Darstellung neu.

Parameter

Name	Typ	Default	Beschreibung
$value	number	100	Nur beim Setzen: neue Größe in Prozent, von `0` bis `100` (Grenzen eingeschlossen). Kommazahlen sind erlaubt.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Größe des Untertitelfelds in Prozent der Videobreite (waagerecht) bzw. Videohöhe (senkrecht). Standardwert ist 100.

Beispiele

Schmalen Untertitel per Skript erzeugen

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

const cue = new VTTCue(1, 5, 'Nur die halbe Breite, rechts ausgerichtet');
cue.size = 50;              // 50 % der Videobreite
cue.position = 100;         // Bezugspunkt am rechten Rand
cue.positionAlign = 'line-right';

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

50

size-Werte aus einer geladenen WebVTT-Datei lesen

// <track src="untertitel.vtt" kind="subtitles" srclang="de" default>
const trackEl = document.querySelector('track');

trackEl.addEventListener('load', () => {
  const cues = Array.from(trackEl.track.cues);
  for (const cue of cues) {
    console.log(`${cue.startTime}s: size=${cue.size}%`);
  }
});

1s: size=100% 6.5s: size=40%

Ungültige Werte abfangen

const cue = new VTTCue(0, 3, 'Hallo');

const setSize = (c, percent) => {
  try {
    c.size = percent;
  } catch (err) {
    console.warn(`${err.name}: ${percent} liegt außerhalb von 0–100`);
    c.size = Math.min(100, Math.max(0, percent)); // auf gültigen Bereich begrenzen
  }
};

setSize(cue, 120);
console.log(cue.size);

IndexSizeError: 120 liegt außerhalb von 0–100 100

// Wichtig · Fallstricke

Liegt der gesetzte Wert unter 0 oder über 100, wirft der Browser eine DOMException vom Typ IndexSizeError. Der alte Wert bleibt dann erhalten.
Der Wert ist eine reine Zahl ohne Prozentzeichen. cue.size = '50%' wird zu NaN umgewandelt und führt zu einem Fehler.
size ist keine Schriftgröße. Die Textgröße steuert man per CSS über das Pseudoelement ::cue.
Browser zeichnen die Einstellung unterschiedlich genau um. Besonders bei senkrechtem Text oder in Kombination mit position und line kann die Darstellung abweichen, daher in mehreren Browsern testen.
VTTCue gibt es nur im Browser. In Node.js existiert die Klasse nicht.

Siehe auch

VTTCue VTTCue.position VTTCue.line VTTCue.vertical DataCue.value