VTTRegion.scroll — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.scroll

Beschreibung

Mit der Eigenschaft scroll legt man fest, wie sich eine VTTRegion verhält, wenn ein neuer Cue (Untertitelzeile) hinzukommt. Erlaubt sind nur zwei Werte des Aufzählungstyps ScrollSetting:

"" (leerer String, Standard): Es wird nicht gescrollt. Neue Cues erscheinen an ihrer Position, bestehende Zeilen bleiben stehen.
"up": Bestehende Cues rutschen nach oben, der neue Cue erscheint in der untersten Zeile. Das entspricht dem klassischen Roll-up-Verhalten von Live-Untertiteln bzw. Closed Captions.

Der Wert "up" eignet sich vor allem für Live-Transkripte, Karaoke-artige Abläufe und alle Fälle, in denen sich Cues zeitlich überschneiden und trotzdem lesbar bleiben sollen. Wie viele Zeilen gleichzeitig sichtbar sind, bestimmt VTTRegion.lines.

In einer WebVTT-Datei entspricht die Eigenschaft der Region-Einstellung scroll:up im REGION-Block. Per JavaScript setzt man sie auf einem VTTRegion-Objekt und weist dieses dann über VTTCue.region einzelnen Cues zu.

Rückgabewert

Typ

"" | "up"

Beschreibung

Die aktuelle Scroll-Einstellung der Region: "up" für Roll-up-Verhalten, "" für kein Scrollen.

Beispiele

Region mit Roll-up-Scrolling anlegen

const region = new VTTRegion();
region.width = 50;       // 50 % der Videobreite
region.lines = 3;        // maximal 3 sichtbare Zeilen
region.regionAnchorX = 0;
region.regionAnchorY = 100;
region.viewportAnchorX = 10;
region.viewportAnchorY = 90;
region.scroll = 'up';    // alte Zeilen nach oben schieben

console.log(region.scroll);

up

Live-Transkript: überlappende Cues in eine scrollende Region legen

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

const region = new VTTRegion();
region.lines = 3;
region.scroll = 'up';

const lines = [
  [0, 6, 'Willkommen zur Live-Übertragung.'],
  [2, 8, 'Heute geht es um WebVTT.'],
  [4, 10, 'Regionen erlauben Roll-up-Untertitel.']
];

for (const [start, end, text] of lines) {
  const cue = new VTTCue(start, end, text);
  cue.region = region; // Cue der scrollenden Region zuweisen
  track.addCue(cue);
}

Ungültige Werte werden ignoriert

const region = new VTTRegion();
console.log(JSON.stringify(region.scroll));

region.scroll = 'down'; // kein gültiger ScrollSetting-Wert
console.log(JSON.stringify(region.scroll));

region.scroll = 'up';
region.scroll = '';     // Scrollen wieder abschalten
console.log(JSON.stringify(region.scroll));

"" "" ""

// Wichtig · Fallstricke

Nur zwei gültige Werte: Wenn man einen anderen String zuweist (z. B. "down" oder "UP"), wird die Zuweisung stillschweigend ignoriert, wie bei WebIDL-Enums für Attribute üblich. Es wird kein Fehler geworfen.
Browser-Kompatibilität: VTTRegion wird von Firefox und Safari unterstützt. In Chromium-basierten Browsern fehlt der Konstruktor oft oder ist nur hinter einem Flag verfügbar. Deshalb vorher mit 'VTTRegion' in window prüfen.
Die Wirkung hängt von der Darstellung durch den Browser ab. Ohne sinnvollen Wert für lines (Standard: 3) und ohne sich überschneidende Cue-Zeiten sieht man den Scroll-Effekt kaum.
Nur Cues, deren region auf diese Region zeigt, scrollen mit. Cues mit eigenem line-Wert, der nicht "auto" ist, werden laut Spezifikation nicht in der Region dargestellt.
Eigene Anzeigen per CSS (z. B. ::cue) beeinflussen das Scrollverhalten nicht.

Siehe auch

VTTRegion VTTRegion.lines VTTRegion.width VTTCue.region VTTCue TextTrack.addCue() StorageEvent.oldValue