DOMRect — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMRect extends DOMRectReadOnly

Beschreibung

DOMRect steht für ein achsenparalleles Rechteck. Es erweitert DOMRectReadOnly und macht die Eigenschaften x, y, width und height beschreibbar. Die abgeleiteten Eigenschaften top, right, bottom und left sind nur lesbar und werden aus den vier Grundwerten berechnet.

Meist begegnet man DOMRect als Rückgabewert von Element.getBoundingClientRect(). Die Methode liefert Position und Größe eines Elements relativ zum Viewport, also dem sichtbaren Bereich. Außerdem bekommt man DOMRect-Objekte von Range.getBoundingClientRect() und als Einträge aus getClientRects(). Typische Einsatzfälle sind Tooltips und Popover positionieren, Kollisionen erkennen, Scroll-Positionen berechnen und Drag-and-Drop umsetzen.

Mit new DOMRect(x, y, width, height) legt man ein Rechteck selbst an. Mit der statischen Methode DOMRect.fromRect() erzeugt man ein Rechteck aus einem Objekt, das die Form eines DOMRectInit hat. toJSON() wandelt das Rechteck in ein einfaches Objekt um, zum Beispiel für Logging oder für JSON.stringify().

Wichtig: width und height dürfen negativ sein. In diesem Fall ist left gleich min(x, x + width), left und x sind dann also nicht dasselbe.

Parameter

Name	Typ	Beschreibung
$x	number	x-Koordinate des Ursprungs (bei positiver Breite die linke Kante).
$y	number	y-Koordinate des Ursprungs (bei positiver Höhe die obere Kante).
$width	number	Breite des Rechtecks. Negative Werte sind erlaubt.
$height	number	Höhe des Rechtecks. Negative Werte sind erlaubt.

Rückgabewert

Typ

DOMRect

Beschreibung

Ein neues DOMRect mit den Eigenschaften x, y, width und height (beschreibbar) sowie top, right, bottom und left (nur lesbar).

Beispiele

DOMRect erzeugen und abgeleitete Werte lesen

const rect = new DOMRect(10, 20, 100, 50);
console.log(rect.right, rect.bottom);

// Grundwerte sind beschreibbar
rect.width = 200;
console.log(rect.right);

// Negative Breite: left ist nicht mehr gleich x
const neg = new DOMRect(100, 0, -40, 10);
console.log(neg.x, neg.left, neg.right);

110 70 210 100 60 100

Tooltip unter einem Button positionieren

const button = document.querySelector('#hilfe');
const tooltip = document.querySelector('#tooltip');

const showTooltip = () => {
  const rect = button.getBoundingClientRect();
  // Viewport-Koordinaten in Dokument-Koordinaten umrechnen
  tooltip.style.left = `${rect.left + window.scrollX}px`;
  tooltip.style.top = `${rect.bottom + window.scrollY + 8}px`;
  tooltip.hidden = false;
};

button.addEventListener('mouseenter', showTooltip);

Überschneidung zweier Rechtecke prüfen

const intersects = (a, b) =>
  a.left < b.right && a.right > b.left &&
  a.top < b.bottom && a.bottom > b.top;

const box1 = DOMRect.fromRect({ x: 0, y: 0, width: 100, height: 100 });
const box2 = new DOMRect(50, 50, 100, 100);
const box3 = new DOMRect(200, 200, 10, 10);

console.log(intersects(box1, box2));
console.log(intersects(box1, box3));
console.log(JSON.stringify(box2.toJSON()));

true false {"x":50,"y":50,"width":100,"height":100,"top":50,"right":150,"bottom":150,"left":50}

// Wichtig · Fallstricke

Viewport-Bezug: Die Werte von getBoundingClientRect() beziehen sich auf den Viewport. Für absolute Koordinaten im Dokument addiert man window.scrollX bzw. window.scrollY.
Momentaufnahme: Ein zurückgegebenes DOMRect wird nicht aktualisiert, wenn gescrollt wird oder sich das Layout ändert. Bei Bedarf fragt man es neu ab.
Performance: Jeder Aufruf von getBoundingClientRect() kann ein synchrones Layout (Reflow) erzwingen. Lese- und Schreibzugriffe auf das DOM sollte man daher bündeln und nicht in schnellen Schleifen abwechseln. Zum Beobachten eignen sich IntersectionObserver und ResizeObserver besser.
Transformationen: CSS-Transforms fließen in das Ergebnis ein. Man erhält das umschließende, achsenparallele Rechteck. Werte können Nachkommastellen haben.
Serialisierung: JSON.stringify(rect) funktioniert über toJSON(). Ein Spread mit {...rect} liefert dagegen ein leeres Objekt, weil die Eigenschaften Getter auf dem Prototyp sind.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere Browser (z. B. der alte Edge/IE) lieferten ClientRect ohne x/y, dort sind left/top die sicherere Wahl. DOMRect gibt es auch in Web Workern.

Siehe auch

DOMRectReadOnly Element.getBoundingClientRect() Element.getClientRects() Range.getBoundingClientRect() IntersectionObserver ResizeObserver DOMPoint