VTTRegion.regionAnchorX — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.regionAnchorX

Beschreibung

Die Eigenschaft regionAnchorX legt fest, welcher horizontale Punkt innerhalb der Region als Ankerpunkt dient. Der Wert ist eine Gleitkommazahl zwischen 0 (linker Rand der Region) und 100 (rechter Rand der Region). Der Standardwert ist 0.

Der Ankerpunkt der Region wird auf den durch viewportAnchorX/viewportAnchorY bestimmten Punkt im Video-Viewport gelegt. Beispiel: Mit regionAnchorX = 50 und viewportAnchorX = 50 wird die Region horizontal zentriert, unabhängig von ihrer Breite. Mit regionAnchorX = 100 und viewportAnchorX = 95 schließt die rechte Kante der Region bei 95 % der Videobreite ab.

In einer WebVTT-Datei entspricht die Eigenschaft dem ersten Wert der Einstellung regionanchor:X%,Y% im REGION-Block. Per JavaScript nutzt man sie, wenn Regionen dynamisch erzeugt oder angepasst werden, etwa um Untertitel je nach Layout links, mittig oder rechts zu verankern. Eine Region wirkt nur auf Cues, deren Eigenschaft region auf sie verweist.

Rückgabewert

Typ

number

Beschreibung

Eine Gleitkommazahl zwischen 0 und 100, die die horizontale Ankerposition in Prozent der Regionsbreite angibt. Standardwert: 0.

Beispiele

Region erzeugen und Anker auslesen

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

region.width = 40;          // 40 % der Videobreite
region.regionAnchorX = 0;   // linker Rand der Region ...
region.viewportAnchorX = 10; // ... liegt bei 10 % der Videobreite
console.log(region.regionAnchorX);

0 0

Untertitel-Region horizontal zentrieren

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

const region = new VTTRegion();
region.width = 60;
region.lines = 3;
region.regionAnchorX = 50;   // Mitte der Region
region.regionAnchorY = 100;  // Unterkante der Region
region.viewportAnchorX = 50; // Mitte des Videos
region.viewportAnchorY = 90; // 90 % der Videohöhe
region.scroll = 'up';

const cue = new VTTCue(0, 5, 'Willkommen zum Vortrag!');
cue.region = region;
track.addCue(cue);

Ungültige Werte abfangen

const region = new VTTRegion();

const setAnchorX = (r, value) => {
  try {
    r.regionAnchorX = value;
    console.log(`Gesetzt: ${r.regionAnchorX}`);
  } catch (err) {
    console.log(`${err.name}: ${value} liegt außerhalb von 0–100`);
  }
};

setAnchorX(region, 75);
setAnchorX(region, 120);

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

Entsprechung in einer WebVTT-Datei

// Inhalt einer .vtt-Datei als String, z. B. für einen Blob-Track
const vtt = `WEBVTT

REGION
id:sprecher
width:40%
lines:3
regionanchor:100%,100%
viewportanchor:95%,90%
scroll:up

00:00:00.000 --> 00:00:04.000 region:sprecher
Rechts unten verankerter Text`;

const url = URL.createObjectURL(new Blob([vtt], { type: 'text/vtt' }));
const trackEl = document.createElement('track');
trackEl.kind = 'subtitles';
trackEl.src = url;
trackEl.default = true;
document.querySelector('video').append(trackEl);

// Wichtig · Fallstricke

Wertebereich: Werte kleiner als 0 oder größer als 100 lösen eine DOMException vom Typ IndexSizeError aus. Nicht-numerische Werte werden in Zahlen umgewandelt; NaN oder Infinity führen zu einem TypeError.
Nicht mit viewportAnchorX verwechseln: regionAnchorX bezieht sich auf die Breite der Region, viewportAnchorX auf die Breite des Videos. Erst beide zusammen bestimmen die Position.
Browser-Kompatibilität: VTTRegion wird von Firefox und Safari unterstützt, in Chromium-Browsern nur hinter einem experimentellen Flag. Vorher per 'VTTRegion' in window prüfen und notfalls auf VTTCue.position/line ausweichen.
Eine Region wirkt nur, wenn sie über cue.region einem Cue zugewiesen ist. Wie Regionen dargestellt werden, kann sich je nach Browser unterscheiden.

Siehe auch

VTTRegion VTTRegion.regionAnchorY VTTRegion.viewportAnchorX VTTRegion.viewportAnchorY VTTRegion.width VTTCue.region VTTCue