new VTTRegion() — Methode · JavaScript-Referenz

Signatur

new VTTRegion()

Beschreibung

Der Konstruktor new VTTRegion() erzeugt eine neue WebVTT-Region. Eine Region ist ein rechteckiger Teilbereich des Videobildes, in dem ein oder mehrere Untertitel-Cues angezeigt werden. Typisch sind mehrzeilige Untertitel, die im Stil von Live-Captions nach oben „wegscrollen“, oder getrennte Bereiche für mehrere Sprecher (z. B. links und rechts).

Der Konstruktor erwartet keine Argumente. Die Region wird mit Standardwerten angelegt: id = "", width = 100 (Prozent), lines = 3, regionAnchorX = 0, regionAnchorY = 100, viewportAnchorX = 0, viewportAnchorY = 100 und scroll = "". Diese Eigenschaften passt du anschließend direkt am Objekt an.

Wirksam wird eine Region erst, wenn du sie einem Cue zuweist: cue.region = region. Mehrere VTTCue-Objekte können dieselbe Region verwenden. Setzt du scroll auf "up", rücken ältere Zeilen nach oben, sobald neue Cues hinzukommen – ideal für dynamisch erzeugte Untertitel, etwa aus einer Spracherkennung.

Rückgabewert

Typ

VTTRegion

Beschreibung

Eine neue VTTRegion-Instanz mit Standardwerten, deren Eigenschaften (id, width, lines, regionAnchorX/Y, viewportAnchorX/Y, scroll) frei konfigurierbar sind.

Beispiele

Region anlegen und Standardwerte prüfen

const region = new VTTRegion();
console.log(region.width, region.lines, region.scroll === '');

100 3 true

Scrollende Live-Untertitel am unteren Bildrand

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

// Region: 80 % breit, 3 Zeilen, unten mittig, scrollt nach oben
const region = new VTTRegion();
region.id = 'live';
region.width = 80;
region.lines = 3;
region.regionAnchorX = 50;
region.regionAnchorY = 100;
region.viewportAnchorX = 50;
region.viewportAnchorY = 90;
region.scroll = 'up';

const addCaption = (start, end, text) => {
  const cue = new VTTCue(start, end, text);
  cue.region = region;
  track.addCue(cue);
};

addCaption(0, 6, 'Willkommen zur Live-Übertragung.');
addCaption(2, 8, 'Heute sprechen wir über WebVTT.');
addCaption(4, 10, 'Regionen ermöglichen scrollende Untertitel.');

Zwei Sprecher in getrennten Regionen

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

const createRegion = (id, anchorX) => {
  const r = new VTTRegion();
  r.id = id;
  r.width = 40;
  r.lines = 2;
  r.regionAnchorX = anchorX;
  r.viewportAnchorX = anchorX;
  r.viewportAnchorY = 85;
  return r;
};

const links = createRegion('anna', 0);
const rechts = createRegion('ben', 100);

const c1 = new VTTCue(1, 4, 'Anna: Hast du das gesehen?');
c1.region = links;
const c2 = new VTTCue(3, 6, 'Ben: Ja, unglaublich!');
c2.region = rechts;

track.addCue(c1);
track.addCue(c2);
console.log(c1.region.id, c2.region.id);

anna ben

// Wichtig · Fallstricke

Browser-Unterstützung: VTTRegion ist nicht Baseline. Die Unterstützung und vor allem die tatsächliche Darstellung (insbesondere scroll = "up") unterscheiden sich zwischen Chromium, Firefox und Safari. Vorher per 'VTTRegion' in window prüfen und notfalls ohne Region arbeiten.
Wertebereiche: width, regionAnchorX/Y und viewportAnchorX/Y sind Prozentwerte von 0 bis 100. Werte außerhalb davon lösen einen IndexSizeError aus. Ein negativer Wert für lines führt ebenfalls zu einem IndexSizeError.
scroll: Erlaubt sind nur "" und "up". Andere Werte werden stillschweigend ignoriert.
Die Region beeinflusst die Darstellung erst, wenn sie per cue.region einem Cue zugewiesen ist und der Track im Modus "showing" läuft. Die frühere Methode TextTrack.addRegion() wurde aus der Spezifikation entfernt.
Die Anzeige von Regionen lässt sich per CSS ::cue-region nur eingeschränkt gestalten, und das wird kaum unterstützt.
Wird die Funktion ohne new aufgerufen, entsteht ein TypeError.

Siehe auch

new CSSSkewY() new Option() new Animation() new RTCError() new VTTCue()