VTTRegion.width — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.width

Beschreibung

Die Eigenschaft width einer VTTRegion legt fest, wie breit der Untertitelbereich ist, und zwar als Prozentsatz der Breite des Video-Viewports. Ein Wert von 40 bedeutet, dass die Region 40 % der Videobreite einnimmt. Der Wert ist eine Gleitkommazahl (double); Nachkommastellen sind also erlaubt.

Regionen braucht man, wenn Untertitel nicht in der üblichen Standardposition erscheinen sollen, zum Beispiel wenn zwei Sprecher links und rechts im Bild getrennte Untertitelbereiche bekommen oder wenn im Stil einer Live-Übertragung zeilenweise nach oben gescrollt wird (scroll = "up"). Zusammen mit lines, regionAnchorX/Y und viewportAnchorX/Y bestimmt width Größe und Position der Region.

In einer WebVTT-Datei entspricht die Eigenschaft der Einstellung width=40% in einem REGION-Block. Erzeugt man Regionen per Skript, setzt man width direkt an einem mit new VTTRegion() erzeugten Objekt und weist die Region anschließend über VTTCue.region einem oder mehreren Cues zu.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	number	100	Neue Breite in Prozent der Videobreite. Muss im Bereich `0` bis `100` liegen, sonst wird ein `IndexSizeError` ausgelöst.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Breite der Region in Prozent (0–100) der Videobreite. Standardwert: 100.

Beispiele

Region per Skript anlegen und einem Cue zuweisen

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

const region = new VTTRegion();
region.id = 'links';
region.width = 40;          // 40 % der Videobreite
region.lines = 3;
region.viewportAnchorX = 5;
region.viewportAnchorY = 90;
region.regionAnchorX = 0;
region.regionAnchorY = 100;

const cue = new VTTCue(1, 4, 'Anna: Hallo zusammen!');
cue.region = region;
track.addCue(cue);

console.log(region.width);

40

Ungültige Werte abfangen

const region = new VTTRegion();
console.log(region.width); // Standardwert

try {
  region.width = 120; // außerhalb von 0–100
} catch (err) {
  console.log(err.name);
}
console.log(region.width); // unverändert

100 IndexSizeError 100

Breite aus einer WebVTT-Datei auslesen

// untertitel.vtt enthält:
// WEBVTT
//
// REGION
// id:sprecher
// width:60%
// lines:2
//
// 00:00.000 --> 00:03.000 region:sprecher
// Willkommen!

const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  const [cue] = trackEl.track.cues;
  if (cue?.region) {
    console.log(`Region "${cue.region.id}": ${cue.region.width} %`);
  }
});

Region "sprecher": 60 %

Breite dynamisch an die Fenstergröße anpassen

const region = new VTTRegion();

const updateWidth = () => {
  // Auf schmalen Bildschirmen breitere Region für bessere Lesbarkeit
  region.width = window.innerWidth < 600 ? 90 : 50;
};

updateWidth();
window.addEventListener('resize', updateWidth);

// Wichtig · Fallstricke

Wertebereich: Werte kleiner als 0 oder größer als 100 lösen beim Setzen einen DOMException vom Typ IndexSizeError aus; der alte Wert bleibt erhalten.
Einheit: Angegeben wird eine reine Zahl ohne %-Zeichen – region.width = '40%' wird zu NaN umgewandelt und führt zu einem TypeError.
Browser-Kompatibilität: WebVTT-Regionen werden nicht überall vollständig unterstützt (nicht Baseline). Vor der Nutzung mit 'VTTRegion' in window prüfen. Auch wenn das Objekt existiert, kann sich die Darstellung (etwa beim Scrollen) zwischen den Browsern unterscheiden.
Ändert man width, nachdem ein Cue schon angezeigt wird, übernehmen manche Browser die Änderung erst beim nächsten Rendern oder beim nächsten Cue.
Die Breite bezieht sich auf den Video-Viewport, nicht auf das CSS-Layout der Seite; mit ::cue-CSS lässt sich die Regionsbreite nicht steuern.

Siehe auch

VTTRegion VTTRegion.lines VTTRegion.viewportAnchorX VTTRegion.regionAnchorX VTTRegion.scroll VTTCue.region VTTCue TextTrack