VTTRegion.viewportAnchorY — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.viewportAnchorY

Beschreibung

Die Eigenschaft viewportAnchorY des Interfaces VTTRegion gibt an, auf welcher vertikalen Position im Videobild die Region verankert wird. Der Wert ist eine Zahl zwischen 0 (oberer Rand) und 100 (unterer Rand), gemessen in Prozent der Höhe des Video-Viewports. Der Standardwert ist 100, also der untere Rand – dort erscheinen Untertitel üblicherweise.

Die Positionierung einer Region ergibt sich aus zwei Ankerpunkten: dem Region-Anker (regionAnchorX/regionAnchorY, ein Punkt innerhalb der Region) und dem Viewport-Anker (viewportAnchorX/viewportAnchorY, ein Punkt im Video). Der Browser verschiebt die Region so, dass beide Punkte übereinanderliegen. Mit viewportAnchorY = 10 und regionAnchorY = 0 hängt die Oberkante der Region z. B. bei 10 % der Videohöhe.

In einer WebVTT-Datei entspricht die Eigenschaft dem zweiten Wert der Einstellung viewportanchor:X%,Y% in einem REGION-Block. Per JavaScript nutzt man sie, um Regionen dynamisch zu erzeugen oder zu verschieben – etwa um Untertitel nach oben zu verlagern, wenn eingeblendete Bedienelemente oder Bauchbinden den unteren Bildbereich verdecken.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	number	100	Prozentwert zwischen `0` und `100` (inklusive). Nachkommastellen sind erlaubt.

Rückgabewert

Typ

number

Beschreibung

Ein double zwischen 0 und 100, der die vertikale Position des Viewport-Ankers in Prozent der Videohöhe angibt.

Beispiele

Region erzeugen und oben im Video verankern

const video = document.querySelector('video');

if ('VTTRegion' in window) {
  const region = new VTTRegion();
  region.width = 80;           // 80 % der Videobreite
  region.lines = 2;
  region.regionAnchorX = 50;   // Mitte der Region …
  region.regionAnchorY = 0;    // … an ihrer Oberkante
  region.viewportAnchorX = 50; // … liegt horizontal mittig
  region.viewportAnchorY = 10; // … und bei 10 % der Videohöhe

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

  const cue = new VTTCue(0, 5, 'Untertitel am oberen Bildrand');
  cue.region = region;
  track.addCue(cue);

  console.log(region.viewportAnchorY);
}

10

Standardwert und Wert aus einer WebVTT-Datei auslesen

// untertitel.vtt enthält:
// REGION
// id:sprecher
// width:40%
// viewportanchor:10%,90%

console.log(new VTTRegion().viewportAnchorY); // Standard

const track = document.querySelector('track');
track.addEventListener('load', () => {
  const cue = track.track.cues[0];
  if (cue?.region) {
    console.log(cue.region.id, cue.region.viewportAnchorY);
  }
});
track.track.mode = 'hidden'; // sorgt dafür, dass die Datei geladen wird

100 sprecher 90

Untertitel ausweichen lassen, wenn Steuerelemente sichtbar sind

const region = new VTTRegion();
region.regionAnchorY = 100; // Unterkante der Region als Bezugspunkt

const setControlsVisible = (visible) => {
  // Bei sichtbarer Steuerleiste Region höher schieben
  region.viewportAnchorY = visible ? 80 : 95;
};

const player = document.querySelector('.player');
player.addEventListener('mouseenter', () => setControlsVisible(true));
player.addEventListener('mouseleave', () => setControlsVisible(false));

Ungültige Werte abfangen

const region = new VTTRegion();

try {
  region.viewportAnchorY = 120;
} catch (err) {
  console.log(err.name);
}
console.log(region.viewportAnchorY); // unverändert

IndexSizeError 100

// Wichtig · Fallstricke

Wertebereich: Werte kleiner als 0 oder größer als 100 werfen eine DOMException vom Typ IndexSizeError; der alte Wert bleibt erhalten. Werte daher vorher begrenzen, z. B. mit Math.min(100, Math.max(0, y)).
Kein Prozentzeichen: Anders als in der WebVTT-Datei (viewportanchor:10%,90%) wird per JavaScript eine reine Zahl ohne % zugewiesen.
Wirkung nur mit Region-Zuweisung: Die Eigenschaft beeinflusst die Darstellung nur, wenn die Region über VTTCue.region mindestens einem Cue zugewiesen ist und der Track im Modus "showing" läuft.
Browser-Unterstützung: VTTRegion wird von Firefox und Safari unterstützt, in Chromium-Browsern bislang nur hinter einem Experimental-Flag. Vorher per 'VTTRegion' in window prüfen; ohne Unterstützung ignorieren Browser Regionen und stellen die Cues an der Standardposition dar.
Eigene Player-Oberflächen, die Untertitel selbst rendern, müssen die Ankerlogik (Region-Anker + Viewport-Anker) selbst nachbilden.

Siehe auch

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