TimeRanges.length — Eigenschaft · JavaScript-Referenz

Signatur

TimeRanges.length

Beschreibung

TimeRanges.length liefert, wie viele getrennte, zusammenhängende Zeitbereiche ein TimeRanges-Objekt enthält. Solche Objekte bekommt man von Medienelementen (<audio>, <video>) über die Eigenschaften buffered, played und seekable sowie von SourceBuffer.buffered bei Media Source Extensions.

Die Eigenschaft ist die Grundlage, um über alle Bereiche zu iterieren: Gültige Indizes für start(index) und end(index) reichen von 0 bis length - 1. TimeRanges ist kein Array und nicht iterierbar – for...of, map() oder der Spread-Operator funktionieren nicht direkt. Man verwendet eine klassische for-Schleife bis length.

Typische Einsatzfälle sind die Anzeige eines Pufferfortschrittsbalkens, das Prüfen, ob eine bestimmte Position bereits geladen ist, oder die Statistik, welche Teile eines Videos tatsächlich angesehen wurden. Ein Wert von 0 bedeutet, dass (noch) kein Bereich vorhanden ist – etwa weil noch nichts gepuffert wurde.

Beispiele

Anzahl gepufferter Bereiche ausgeben

const video = document.querySelector('video');

video.addEventListener('progress', () => {
  const { buffered } = video;
  console.log(`Gepufferte Bereiche: ${buffered.length}`);
});

Gepufferte Bereiche: 1

Alle Bereiche in ein Array umwandeln

const rangesToArray = (ranges) => {
  const result = [];
  for (let i = 0; i < ranges.length; i++) {
    result.push({ start: ranges.start(i), end: ranges.end(i) });
  }
  return result;
};

const video = document.querySelector('video');
video.addEventListener('pause', () => {
  console.table(rangesToArray(video.played));
});

[{ start: 0, end: 12.4 }, { start: 30, end: 41.8 }]

Prüfen, ob eine Position bereits gepuffert ist

const isBuffered = (media, time) => {
  const { buffered } = media;
  for (let i = 0; i < buffered.length; i++) {
    if (time >= buffered.start(i) && time <= buffered.end(i)) {
      return true;
    }
  }
  return false;
};

const video = document.querySelector('video');
console.log(isBuffered(video, 60)); // Sprung zu 1:00 ohne Nachladen möglich?

false

Pufferfortschritt in Prozent berechnen

const video = document.querySelector('video');
const bar = document.querySelector('#buffer-bar');

video.addEventListener('progress', () => {
  const { buffered, duration } = video;
  if (buffered.length === 0 || !Number.isFinite(duration)) return;
  // Ende des letzten Bereichs als grobe Näherung
  const loadedUntil = buffered.end(buffered.length - 1);
  bar.style.width = `${(loadedUntil / duration) * 100}%`;
});

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an length wird ignoriert (im Strict Mode TypeError).
Leere Objekte: Bei length === 0 werfen start(0) und end(0) eine IndexSizeError-DOMException. Vorher immer length prüfen.
Momentaufnahme: Ein TimeRanges-Objekt ist nicht „live“. Nach neuen Ladevorgängen muss media.buffered erneut abgefragt werden, sonst liefert length veraltete Werte.
Nicht iterierbar: Array.from(ranges) oder for...of funktionieren nicht – eine Indexschleife bis length verwenden.
Bereiche sind normalisiert: sie überlappen sich nicht und sind aufsteigend sortiert; angrenzende Bereiche werden vom Browser zusammengeführt.
Kompatibilität: In allen modernen Browsern seit Langem unterstützt.

Siehe auch

Storage.length DOMStringList.length FileList.length MediaList.length Summarizer.length