Signatur
Beschreibung
DOMRectList ist eine schreibgeschützte, array-ähnliche Sammlung von DOMRect-Objekten. Sie begegnet dir vor allem als Rückgabewert von Element.prototype.getClientRects() und Range.prototype.getClientRects(). Jedes enthaltene Rechteck beschreibt eine CSS-Box (bzw. ein Box-Fragment) relativ zum Viewport.
Wichtig wird das bei Inline-Elementen, die über mehrere Zeilen umbrechen: Während getBoundingClientRect() nur ein einziges umschließendes Rechteck liefert, bekommst du über getClientRects() für jede Zeile ein eigenes Rechteck. Damit lassen sich z. B. Textmarkierungen, Tooltips an der richtigen Zeile oder eigene Hervorhebungen exakt positionieren.
Die Schnittstelle bietet nur die Eigenschaft length und die Methode item(index); zusätzlich ist ein Indexzugriff per list[i] möglich. DOMRectList ist iterierbar, du kannst sie also mit for...of, Spread-Syntax oder Array.from() verarbeiten.
Die Liste ist ein statischer Schnappschuss: Sie aktualisiert sich nicht, wenn sich Layout, Scrollposition oder Inhalt später ändern. Frag die Rechtecke bei Bedarf einfach neu ab.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Schreibgeschützte Eigenschaft: Anzahl der enthaltenen DOMRect-Objekte. |
|
| $item(index) | (index: number) => DOMRect | null | Methode: gibt das DOMRect an Position index zurück, oder null, wenn der Index außerhalb des gültigen Bereichs liegt. |
|
| $[index] | DOMRect | undefined | Indexzugriff wie bei Arrays; liefert bei ungültigem Index undefined (nicht null). |
Rückgabewert
DOMRect-Objekten (Koordinaten relativ zum Viewport, in CSS-Pixeln).Beispiele
Rechtecke eines umbrechenden Inline-Elements auslesen
// <p style="width:150px">Text mit <span id="hl">einem längeren hervorgehobenen Abschnitt</span></p>
const span = document.querySelector('#hl');
const rects = span.getClientRects();
console.log(rects instanceof DOMRectList); // true
console.log('Anzahl Zeilen:', rects.length);
for (const rect of rects) {
console.log(`x=${Math.round(rect.x)} y=${Math.round(rect.y)} w=${Math.round(rect.width)}`);
}item() vs. Indexzugriff und Umwandlung in ein Array
const rects = document.body.getClientRects();
console.log(rects.item(0) === rects[0]); // true
console.log(rects.item(99)); // null
console.log(rects[99]); // undefined
// Für Array-Methoden zuerst umwandeln
const widths = Array.from(rects, (r) => r.width);
const total = [...rects].reduce((sum, r) => sum + r.height, 0);
console.log(widths, total);Markierte Textauswahl zeilenweise hervorheben
document.addEventListener('mouseup', () => {
document.querySelectorAll('.sel-box').forEach((el) => el.remove());
const selection = window.getSelection();
if (!selection || selection.rangeCount === 0 || selection.isCollapsed) return;
const rects = selection.getRangeAt(0).getClientRects(); // DOMRectList
for (const { left, top, width, height } of rects) {
const box = document.createElement('div');
box.className = 'sel-box';
Object.assign(box.style, {
position: 'absolute',
left: `${left + window.scrollX}px`,
top: `${top + window.scrollY}px`,
width: `${width}px`,
height: `${height}px`,
background: 'rgba(255, 220, 0, 0.35)',
pointerEvents: 'none'
});
document.body.append(box);
}
});// Wichtig · Fallstricke
- Kein echtes Array: Methoden wie
map(),filter()oderforEach()gibt es nicht. VerwendeArray.from()oder Spread-Syntax. - Statischer Schnappschuss: Nach Scrollen, Größenänderungen oder DOM-Änderungen sind die Werte veraltet. Die Koordinaten beziehen sich auf den Viewport, für Dokumentkoordinaten musst du
window.scrollX/scrollYaddieren. - Leere Liste: Bei Elementen mit
display: noneoder ohne zugehörige Box istlengthgleich0. Frag das also vor dem Zugriff aufrects[0]ab. - Performance: Jeder Aufruf von
getClientRects()kann ein synchrones Layout (Reflow) erzwingen. Vermeide es, Lesen und Schreiben in Schleifen abzuwechseln (sogenanntes Layout-Thrashing). - Legacy-Schnittstelle: Laut Spezifikation soll
DOMRectListnur aus Kompatibilitätsgründen bestehen bleiben, neue APIs geben stattdessen normale Arrays zurück. Die Unterstützung ist in allen modernen Browsern stabil.