DOMRectList.length — Eigenschaft · JavaScript-Referenz

Signatur

DOMRectList.length

Beschreibung

Die Eigenschaft length einer DOMRectList gibt an, wie viele DOMRect-Objekte die Liste enthält. Solche Listen erhalten Sie vor allem von Element.getClientRects() und Range.getClientRects(). Beide Methoden liefern für jede Rahmenbox (border box) bzw. für jedes Textfragment ein eigenes Rechteck.

Nützlich ist length vor allem bei Inline-Elementen, die über mehrere Zeilen umbrechen. Ein <span>, der sich über drei Zeilen erstreckt, liefert drei Rechtecke. Mit length können Sie also die Anzahl der Zeilen ermitteln, prüfen, ob ein Element überhaupt dargestellt wird (length === 0 bei display: none oder bei Elementen außerhalb des Dokuments), oder in einer klassischen for-Schleife über die Rechtecke laufen.

Der Wert ist eine nicht negative Ganzzahl und lässt sich nicht verändern: Zuweisungen werden im nicht strikten Modus stillschweigend ignoriert. Die Liste ist eine statische Momentaufnahme. Ändert sich danach das Layout, bleibt length gleich. Für aktuelle Werte müssen Sie getClientRects() erneut aufrufen.

Rückgabewert

Typ

number

Beschreibung

Nicht negative Ganzzahl mit der Anzahl der DOMRect-Objekte in der Liste. Sie ist 0, wenn keine Rahmenbox erzeugt wird.

Beispiele

Zeilenanzahl eines umbrechenden Inline-Elements ermitteln

const span = document.createElement('span');
span.textContent = 'Dies ist ein längerer Text, der in einem schmalen Container über mehrere Zeilen umbricht.';
const box = document.createElement('div');
box.style.width = '150px';
box.append(span);
document.body.append(box);

const rects = span.getClientRects();
console.log(`Der Text belegt ${rects.length} Zeilen.`);

Der Text belegt 4 Zeilen. (je nach Schrift und Browser)

Prüfen, ob ein Element dargestellt wird

const isRendered = (el) => el.getClientRects().length > 0;

const hint = document.createElement('p');
hint.textContent = 'Hinweis';
document.body.append(hint);
console.log(isRendered(hint));

hint.style.display = 'none';
console.log(isRendered(hint));

true false

Mit length über alle Rechtecke einer Textauswahl iterieren

const p = document.createElement('p');
p.textContent = 'Markiere mich bitte über mehrere Zeilen hinweg, damit mehrere Rechtecke entstehen.';
p.style.width = '200px';
document.body.append(p);

const range = document.createRange();
range.selectNodeContents(p);
const rects = range.getClientRects();

for (let i = 0; i < rects.length; i++) {
  const { left, top, width, height } = rects[i];
  console.log(`#${i}: x=${Math.round(left)}, y=${Math.round(top)}, ${Math.round(width)}×${Math.round(height)}`);
}

#0: x=8, y=16, 190×18 #1: x=8, y=34, 185×18 ... (werte abhängig vom Layout)

// Wichtig · Fallstricke

Statische Liste: length ändert sich nicht, wenn sich das Layout ändert. Rufen Sie nach Größen- oder Inhaltsänderungen getClientRects() erneut auf.
Layout erzwingen: Jeder Aufruf von getClientRects() kann ein synchrones Neuberechnen des Layouts (Reflow) auslösen. Rufen Sie die Methode deshalb in Schleifen oder bei scroll-/resize-Ereignissen nicht unnötig oft auf.
Nicht dargestellte Elemente: Bei display: none, bei Elementen außerhalb des Dokuments und bei manchen SVG-Konstellationen ist length gleich 0. Bei visibility: hidden ist length dagegen größer als 0.
Kein echtes Array: DOMRectList hat kein map, filter usw. Verwenden Sie Array.from(rects) oder [...rects], denn die Liste ist iterierbar.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. In älteren Browsern hieß die Schnittstelle teilweise ClientRectList, length verhält sich dort gleich.

Siehe auch

DOMRectList DOMRectList.item() DOMRect Element.getClientRects() Range.getClientRects() Element.getBoundingClientRect() AudioTrackList.length