VTTRegion.lines — Eigenschaft · JavaScript-Referenz

Signatur

VTTRegion.lines

Beschreibung

Die Eigenschaft lines eines VTTRegion-Objekts legt fest, wie viele Textzeilen die Region hoch ist. Eine Region ist ein fester Bereich im Video, in dem Untertitel-Cues (VTTCue) angezeigt werden. Die Höhe wird bewusst in Zeilen und nicht in Pixeln oder Prozent angegeben. So passt sich die Region an die Schriftgröße an, die der Browser gerade verwendet.

Wichtig ist das vor allem bei Roll-up-Untertiteln, wie sie bei Live-Übertragungen üblich sind. Kommt ein neuer Cue dazu und ist die Region schon voll, rutschen die älteren Zeilen nach oben aus dem sichtbaren Bereich. Das gilt, wenn scroll den Wert "up" hat. Wie viele Zeilen gleichzeitig zu sehen sind, bestimmt also direkt lines.

Die Eigenschaft entspricht der Einstellung lines: in einem REGION-Block einer WebVTT-Datei. Wenn der Browser eine .vtt-Datei einliest, wird der dort angegebene Wert in lines übernommen. Legen Sie eine Region selbst mit new VTTRegion() an, ist der Wert zunächst 3.

Parameter

Name	Typ	Default	Beschreibung
$value	number	3	Nur beim Setzen: die gewünschte Höhe der Region in Zeilen. Das Attribut ist in der Spezifikation als `unsigned long` festgelegt. Der Wert wird deshalb in eine ganze Zahl ohne Vorzeichen umgewandelt.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl: die Höhe der Region in Zeilen.

Beispiele

Region mit zwei Zeilen anlegen und einem Cue zuweisen

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

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

region.lines = 2;          // Region nur zwei Zeilen hoch
region.width = 60;         // 60 % der Videobreite
region.scroll = 'up';      // Roll-up-Verhalten

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

console.log(cue.region.lines);

3 2

Roll-up-Untertitel für eine Live-Übertragung

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

const liveRegion = new VTTRegion();
liveRegion.lines = 3;
liveRegion.scroll = 'up';
liveRegion.viewportAnchorY = 90; // Region unten im Bild

const zeilen = ['Guten Abend,', 'hier sind die Nachrichten.', 'Zuerst das Wetter.', 'Morgen wird es sonnig.'];

zeilen.forEach((text, i) => {
  const cue = new VTTCue(i * 2, i * 2 + 6, text);
  cue.region = liveRegion;
  track.addCue(cue);
});
// Es sind höchstens 3 Zeilen gleichzeitig zu sehen, ältere rutschen nach oben hinaus.

Wert aus einer eingelesenen WebVTT-Datei auslesen

// untertitel.vtt enthält:
// WEBVTT
//
// REGION
// id:sprecher
// width:40%
// lines:4
// scroll:up
//
// 00:00.000 --> 00:04.000 region:sprecher
// Erste Zeile

const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  const [cue] = trackEl.track.cues;
  if (cue?.region) {
    console.log(`Region "${cue.region.id}": ${cue.region.lines} Zeilen`);
  }
});

Region "sprecher": 4 Zeilen

// Wichtig · Fallstricke

Browser-Unterstützung: VTTRegion gibt es in Firefox und Safari. In Chromium-Browsern (Chrome, Edge) ist die Schnittstelle standardmäßig nicht verfügbar. Prüfen Sie das vor der Verwendung, zum Beispiel mit 'VTTRegion' in window, und sehen Sie eine Darstellung ohne Regionen als Ausweichlösung vor.
Umwandlung in eine ganze Zahl: Weil das Attribut als unsigned long festgelegt ist, werden Nachkommastellen abgeschnitten, aus 2.7 wird also 2. Negative Zahlen werden nach den WebIDL-Regeln umgerechnet und ergeben sehr große Werte statt einer Fehlermeldung. Prüfen Sie Eingaben deshalb vorher selbst. In älteren Fassungen der Spezifikation wurde bei negativen Werten ein IndexSizeError ausgelöst.
Der Wert 0 ist erlaubt, führt aber dazu, dass in der Region nichts zu sehen ist.
Die Höhe in Pixeln ergibt sich aus lines und der Zeilenhöhe, die der Browser beim Darstellen verwendet. Wie hoch die Region tatsächlich wird, kann deshalb je nach Browser und Nutzereinstellung (z. B. Untertitelgröße) unterschiedlich sein.
Wird lines nachträglich geändert, während Cues angezeigt werden, übernehmen manche Browser die neue Höhe erst beim nächsten Cue-Wechsel.

Siehe auch

VTTRegion VTTRegion.width VTTRegion.scroll VTTRegion.viewportAnchorY VTTCue.region VTTCue TextTrack.addCue()