VTTRegion.viewportAnchorX — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.viewportAnchorX

Beschreibung

Die Eigenschaft viewportAnchorX der Schnittstelle VTTRegion legt fest, an welcher horizontalen Stelle des Videobilds eine Untertitel-Region verankert wird. Der Wert ist eine Zahl zwischen 0 (linker Rand) und 100 (rechter Rand) und wird als Prozent der Videobreite interpretiert. Der Standardwert ist 0.

Der Viewport-Anker arbeitet mit dem Regions-Anker (regionAnchorX/regionAnchorY) zusammen: Der Punkt innerhalb der Region, der durch den Regions-Anker bestimmt ist, wird genau auf den Punkt im Video gelegt, den viewportAnchorX und viewportAnchorY angeben. So lassen sich Regionen z. B. zentriert (50/50) oder rechtsbündig (100/100) positionieren, unabhängig von der Größe des Players.

In einer WebVTT-Datei entspricht die Eigenschaft dem ersten Wert der Regions-Einstellung viewportanchor:X%,Y%. Per JavaScript nutzt man sie, um Regionen dynamisch zu erzeugen oder anzupassen – etwa für Sprecher-Untertitel links und rechts im Bild oder zum Ausweichen vor eingeblendeten Bedienelementen.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Beim Setzen: Prozentwert zwischen `0` und `100` (Gleitkommazahl erlaubt) für die horizontale Ankerposition im Video.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle x-Koordinate des Viewport-Ankers in Prozent der Videobreite (0–100).

Beispiele

Region rechts im Bild verankern

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

const region = new VTTRegion();
region.width = 40;          // 40 % der Videobreite
region.lines = 3;
region.regionAnchorX = 100; // rechter Rand der Region ...
region.regionAnchorY = 100;
region.viewportAnchorX = 95; // ... sitzt bei 95 % der Videobreite
region.viewportAnchorY = 90;

const cue = new VTTCue(0, 5, 'Sprecher B: Hallo!');
cue.region = region;
track.addCue(cue);

console.log(region.viewportAnchorX);

95

Wert aus einer geladenen WebVTT-Datei auslesen

// untertitel.vtt enthält:
// REGION
// id:links
// viewportanchor:10%,90%
const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  for (const cue of trackEl.track.cues) {
    if (cue.region) {
      console.log(cue.region.id, cue.region.viewportAnchorX);
    }
  }
});

links 10

Ungültige Werte abfangen und Region verschieben

const region = new VTTRegion();

const setAnchorX = (r, percent) => {
  try {
    r.viewportAnchorX = percent;
  } catch (err) {
    console.warn(`Ungültiger Wert ${percent}:`, err.name);
  }
};

setAnchorX(region, 50);
setAnchorX(region, 120);
console.log(region.viewportAnchorX);

Ungültiger Wert 120: IndexSizeError 50

// Wichtig · Fallstricke

Wertebereich: Werte kleiner als 0 oder größer als 100 lösen eine DOMException vom Typ IndexSizeError aus; der alte Wert bleibt erhalten.
Kein Prozentzeichen: Anders als in der VTT-Datei (viewportanchor:10%,90%) wird in JavaScript nur die Zahl zugewiesen, nicht der String '10%'.
Die Wirkung hängt immer vom Zusammenspiel mit regionAnchorX und width ab – wer nur viewportAnchorX = 100 setzt, schiebt die Region bei regionAnchorX = 0 aus dem sichtbaren Bereich.
Browser-Kompatibilität: VTTRegion ist nicht überall verfügbar (u. a. in Firefox und Safari, in Chromium-Browsern nur eingeschränkt bzw. hinter Flags). Vor der Nutzung mit 'VTTRegion' in window prüfen; Regionen aus VTT-Dateien werden ohne Unterstützung ignoriert.

Siehe auch

VTTRegion VTTRegion.viewportAnchorY VTTRegion.regionAnchorX VTTRegion.width VTTCue.region TextTrack.addCue() TaskAttributionTiming.containerSrc