CKTIS / JavaScript
Element.getBoundingClientRect(): Maße und Position eines DOMRect
Miss das umschließende Rechteck eines Elements in CSS-Pixeln und unterscheide Koordinaten relativ zum Anzeigebereich von Dokumentkoordinaten.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
const rect = element.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;element.getBoundingClientRect() nimmt keine Argumente entgegen und gibt ein DOMRect zurück. Die Methode ist eine Web-API und nicht Teil von ECMAScript. Für die Messung brauchst du eine Umgebung mit DOM-Layout; die Verfügbarkeit hängt von der Laufzeitumgebung ab.
Bei einem HTML-Element beruht die Messung auf achsenparallelen Rechtecken für seine CSS-Rahmenboxen. Sie schließt Innenabstände und Rahmen ein, berücksichtigt CSS-Transformationen und lässt Außenabstände außen vor. Die einzelnen Rechtecke erhältst du mit getClientRects(). Ist die Liste leer, etwa bei display: none, sind alle Werte null. Hat jedes Rechteck eine Breite oder Höhe von null, gibt die Methode das erste Rechteck der Liste zurück. Andernfalls gibt sie das kleinste Rechteck zurück, das alle Rechtecke der Liste umschließt, außer denen, deren Breite und Höhe beide null sind. Bei einem Inline-Element über mehrere Zeilen kann das Ergebnis auch Zwischenräume zwischen den Fragmenten umfassen. Das Rechteck allein beweist nicht, dass das Element sichtbar ist.
width und height sind die Maße des Rechtecks. In diesem Ergebnis entsprechen x und y den Werten left und top; right ist left + width und bottom ist top + height. Der Ursprung liegt oben links im Anzeigebereich, nicht an dessen jeweils nächster Kante. Deshalb können Koordinaten negativ sein. Alle Werte sind in CSS-Pixeln angegeben und können Nachkommastellen haben.
Bei einem DOMRect sind x, y, width und height veränderbar; die Kantenwerte werden daraus berechnet und sind schreibgeschützt. Bei einem manuell erzeugten Rechteck mit negativem width oder height kann x von left oder y von top abweichen. Änderungen am Ergebnis ändern das Element nicht. Das Ergebnis ist eine Momentaufnahme: Miss nach Layoutänderungen oder Scrollen erneut, wenn du aktuelle Werte brauchst.
Für die linke obere Ecke in Dokumentkoordinaten verwende rect.left + window.scrollX und rect.top + window.scrollY. Lies die Scrollwerte bei der Messung ab. Damit änderst du den Koordinatenursprung, hebst aber keine Scrollbewegung in einem verschachtelten Container auf.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Measuring an element</title>
</head>
<body>
<script>
(() => {
const box = document.createElement('div');
box.style.cssText = 'position: fixed; left: 24.5px; top: 16px; margin: 0; box-sizing: content-box; width: 104px; height: 44px; padding: 8px; border: 0;';
document.body.append(box);
try {
const rect = box.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;
console.log(`x=${x}, y=${y}, width=${width}, height=${height}, top=${top}, right=${right}, bottom=${bottom}, left=${left}`);
box.style.left = '44.5px';
console.log(`previous x=${rect.x}, current x=${box.getBoundingClientRect().x}`);
} finally {
box.remove();
}
})();
</script>
</body>
</html>Ergebnis
x=24.5, y=16, width=120, height=60, top=16, right=144.5, bottom=76, left=24.5 previous x=24.5, current x=44.5
Speichere das Beispiel als HTML-Datei, öffne sie im Browser und lies die Ausgabe in der Entwicklerkonsole ab. Die Maße enthalten den Innenabstand auf beiden Seiten jeder Achse; das Element hat keinen Rahmen. Nach dem Verschieben behält das alte Rechteck seinen ursprünglichen Wert für `x`; erst eine neue Messung liefert das neue `x`.
Zugehörige Lektionen
- JavaScript · Lektion 12 · Fortgeschritten · Version: 4