Signatur
Beschreibung
DOMRectReadOnly ist die Basisschnittstelle für rechteckige Bereiche im DOM. Sie stellt die Koordinaten x und y (linke obere Ecke) sowie width und height bereit. Zusätzlich gibt es die abgeleiteten Eigenschaften top, right, bottom und left, die auch bei negativen Breiten oder Höhen immer die tatsächlichen Kanten liefern.
Man trifft die Schnittstelle vor allem als Rückgabewert von Web-APIs an: ResizeObserverEntry.contentRect, IntersectionObserverEntry.boundingClientRect, intersectionRect und rootBounds sind DOMRectReadOnly-Objekte. Element.getBoundingClientRect() liefert dagegen die veränderbare Unterklasse DOMRect, die sich aber genauso auslesen lässt.
Eigene Instanzen erzeugt man mit dem Konstruktor new DOMRectReadOnly(x, y, width, height) oder mit der statischen Methode DOMRectReadOnly.fromRect(obj). Die Methode toJSON() gibt ein einfaches Objekt mit allen Eigenschaften zurück, das sich z. B. zum Protokollieren oder Übertragen serialisieren lässt.
- Eigenschaften:
x,y,width,height,top,right,bottom,left(allenumber, nur lesbar) - Methoden:
toJSON(), statischDOMRectReadOnly.fromRect()
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $x | number | 0 | X-Koordinate des Ursprungs (in der Regel die linke Kante). |
| $y | number | 0 | Y-Koordinate des Ursprungs (in der Regel die obere Kante). |
| $width | number | 0 | Breite des Rechtecks; darf negativ sein. |
| $height | number | 0 | Höhe des Rechtecks; darf negativ sein. |
Rückgabewert
new DOMRectReadOnly() oder DOMRectReadOnly.fromRect()).Beispiele
Instanz erzeugen und Kanten auslesen
const rect = new DOMRectReadOnly(10, 20, 200, 100);
console.log(rect.left, rect.top); // linke obere Ecke
console.log(rect.right, rect.bottom); // rechte untere Ecke
// Zuweisungen werden ignoriert (im Strict Mode: TypeError)
rect.width = 999;
console.log(rect.width);Größenänderungen mit ResizeObserver verfolgen
const box = document.querySelector('#panel');
const observer = new ResizeObserver((entries) => {
for (const entry of entries) {
// contentRect ist ein DOMRectReadOnly
const { width, height } = entry.contentRect;
console.log(`Neue Größe: ${Math.round(width)} × ${Math.round(height)} px`);
}
});
observer.observe(box);fromRect() und toJSON() zum Serialisieren
const rect = DOMRectReadOnly.fromRect({ x: 5, y: 5, width: 50, height: -20 });
// Negative Höhe: top/bottom werden korrekt normalisiert
console.log(rect.y, rect.top, rect.bottom);
console.log(JSON.stringify(rect.toJSON()));Überlappung zweier Rechtecke prüfen
const overlaps = (a, b) =>
a.left < b.right && a.right > b.left &&
a.top < b.bottom && a.bottom > b.top;
const a = new DOMRectReadOnly(0, 0, 100, 100);
const b = new DOMRectReadOnly(50, 50, 100, 100);
const c = new DOMRectReadOnly(200, 0, 10, 10);
console.log(overlaps(a, b), overlaps(a, c));// Wichtig · Fallstricke
- Nur lesbar: Zuweisungen an Eigenschaften werden im Sloppy Mode stillschweigend ignoriert, im Strict Mode (z. B. in ES-Modulen) lösen sie einen
TypeErroraus. Für veränderbare Rechtecke nutzt manDOMRect. - Negative Maße:
x/ysind nicht immer die linke/obere Kante. Wenn Breite oder Höhe negativ sein können, verwendet man besserleft,top,rightundbottom. - Keine eigenen Eigenschaften: Die Werte sind Getter auf dem Prototyp.
JSON.stringify(rect)funktioniert nur, weiltoJSON()existiert. Mit Spread ({...rect}) oderObject.keys()erhält man dagegen ein leeres Objekt. - Momentaufnahme: Das Objekt wird nicht automatisch aktualisiert. Nach Layout-Änderungen müssen die Werte neu abgefragt werden.
- Kompatibilität: Wird von allen modernen Browsern unterstützt.
fromRect()fehlt in alten Safari- und Edge-Versionen (EdgeHTML), und der Internet Explorer kennt nur ein älteresClientRectohnex/y.