VTTRegion.regionAnchorY — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.regionAnchorY

Beschreibung

Die Eigenschaft regionAnchorY der Schnittstelle VTTRegion gibt an, wo innerhalb der Region ihr Ankerpunkt senkrecht liegt. Der Wert ist eine Gleitkommazahl zwischen 0 (Oberkante der Region) und 100 (Unterkante der Region). Der Standardwert ist 100, der Anker sitzt also normalerweise an der Unterkante.

Der Ankerpunkt allein legt die Position noch nicht fest. Er wird immer zusammen mit dem Viewport-Anker (viewportAnchorX/viewportAnchorY) ausgewertet: Der Browser verschiebt die Region so, dass ihr Ankerpunkt (regionAnchorX/regionAnchorY) genau auf dem Viewport-Anker im Videobild liegt. Beispiel: Mit regionAnchorY = 100 und viewportAnchorY = 90 liegt die Unterkante der Region bei 90 % der Videohöhe.

In einer WebVTT-Datei entspricht die Eigenschaft dem zweiten Wert der Einstellung regionanchor im REGION-Block, z. B. regionanchor:0%,100%. Per JavaScript nutzt man die Eigenschaft vor allem dann, wenn Untertitelregionen dynamisch erzeugt oder angepasst werden, etwa um Untertitel nach oben zu verschieben, sobald eine Bedienleiste eingeblendet ist.

Parameter

Name	Typ	Default	Beschreibung
$value	number	100	Beim Setzen: Prozentwert von `0` bis einschließlich `100`, bezogen auf die Höhe der Region. Werte außerhalb dieses Bereichs lösen einen `IndexSizeError` aus.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle y-Koordinate des Regionsankers in Prozent der Regionshöhe (Gleitkommazahl, 0–100).

Beispiele

Region erzeugen und senkrecht verankern

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

const region = new VTTRegion();
region.width = 60;          // 60 % der Videobreite
region.lines = 3;           // drei Zeilen hoch
region.regionAnchorX = 50;  // horizontale Mitte der Region …
region.regionAnchorY = 100; // … an ihrer Unterkante
region.viewportAnchorX = 50;
region.viewportAnchorY = 90; // liegt bei 90 % der Videohöhe

const cue = new VTTCue(0, 5, 'Hallo und willkommen!');
cue.region = region;
track.addCue(cue);

console.log(region.regionAnchorY);

100

Untertitel beim Einblenden der Bedienleiste nach oben schieben

const video = document.querySelector('video');
const region = new VTTRegion();
region.regionAnchorY = 100;
region.viewportAnchorY = 95;

const track = video.addTextTrack('captions', 'Deutsch', 'de');
track.mode = 'showing';
const cue = new VTTCue(0, 60, 'Untertitel über der Steuerleiste');
cue.region = region;
track.addCue(cue);

// Beim Hover: Region mit ihrer Unterkante höher anheften
video.addEventListener('mouseenter', () => {
  region.viewportAnchorY = 80;
});
video.addEventListener('mouseleave', () => {
  region.viewportAnchorY = 95;
});

Werte aus einer geladenen WebVTT-Datei auslesen und validieren

// untertitel.vtt enthält:
// REGION
// id:oben
// regionanchor:0%,0%
// viewportanchor:10%,10%
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.regionAnchorY);
    }
  }
});

// Ungültige Werte abfangen
const region = new VTTRegion();
try {
  region.regionAnchorY = 150;
} catch (err) {
  console.log(err.name);
}

oben 0 IndexSizeError

// Wichtig · Fallstricke

Wertebereich: Nur 0–100 ist erlaubt. Größere oder negative Werte lösen einen IndexSizeError (DOMException) aus und werden nicht stillschweigend begrenzt. Das Prozentzeichen wird nicht mitgeschrieben: Man setzt 50, nicht '50%'.
Bezugsgröße: Der Prozentwert bezieht sich auf die Höhe der Region, nicht auf die Höhe des Videos. Diese Regionshöhe ergibt sich aus lines und der Zeilenhöhe. Für die Position im Video ist viewportAnchorY zuständig.
Kompatibilität: VTTRegion gibt es in Chromium-Browsern und in Safari. In Firefox ist die Unterstützung eingeschränkt oder hängt von einer Einstellung ab. Vor der Verwendung sollte man mit 'VTTRegion' in window prüfen, ob die Schnittstelle vorhanden ist. Ohne Unterstützung zeigt der Browser Cues an ihrer Standardposition an.
Regionen wirken nur bei horizontalen Cues (vertical leer). Die Cue-Einstellungen line, size und position werden innerhalb einer Region teilweise ignoriert.

Siehe auch

VTTRegion VTTRegion.regionAnchorX VTTRegion.viewportAnchorY VTTRegion.viewportAnchorX VTTRegion.lines VTTCue.region VTTCue