new DOMRectReadOnly() — Methode · JavaScript-Referenz

Signatur

new DOMRectReadOnly(x, y, width, height)

Beschreibung

Mit new DOMRectReadOnly() erzeugen Sie ein Rechteck, dessen Eigenschaften sich nach dem Erstellen nicht mehr ändern lassen. Es stellt x, y, width und height bereit. Daraus werden top, right, bottom und left berechnet, auch wenn Breite oder Höhe negativ sind.

Solche Objekte liefert der Browser zum Beispiel bei ResizeObserverEntry.contentRect oder IntersectionObserverEntry.boundingClientRect. Den Konstruktor brauchen Sie selbst, wenn Sie eigene Geometriedaten in derselben Form darstellen wollen. Typische Fälle sind Tests mit nachgebauten Observer-Einträgen, eine Hilfsfunktion für Kollisionsprüfungen oder Werte, die unterwegs niemand verändern soll.

Alle Argumente sind optional und haben den Standardwert 0. Übergebene Werte werden als double in Zahlen umgewandelt. Brauchen Sie ein veränderbares Rechteck, nehmen Sie die Unterklasse DOMRect. Um ein Rechteck aus einem vorhandenen Objekt zu erzeugen, gibt es die statische Methode DOMRectReadOnly.fromRect().

Parameter

Name	Typ	Beschreibung
$x	number	X-Koordinate des Ursprungs, meist die linke obere Ecke.
$y	number	Y-Koordinate des Ursprungs.
$width	number	Breite des Rechtecks. Sie darf negativ sein, dann liegt der Ursprung rechts.
$height	number	Höhe des Rechtecks. Sie darf negativ sein, dann liegt der Ursprung unten.

Rückgabewert

Typ

DOMRectReadOnly

Beschreibung

Ein neues, unveränderliches DOMRectReadOnly-Objekt mit den angegebenen Werten.

Beispiele

Rechteck erzeugen und abgeleitete Werte lesen

const rect = new DOMRectReadOnly(10, 20, 100, 50);

console.log(rect.x, rect.y, rect.width, rect.height);
console.log(rect.top, rect.right, rect.bottom, rect.left);

10 20 100 50 20 110 70 10

Werte lassen sich nicht ändern

'use strict';
const rect = new DOMRectReadOnly(0, 0, 200, 100);

try {
  rect.width = 500; // Die Eigenschaft hat nur einen Getter
} catch (err) {
  console.log(err.name);
}
console.log(rect.width);

TypeError 200

Kollisionsprüfung mit negativer Breite

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

const player = new DOMRectReadOnly(50, 50, 32, 32);
// Negative Breite: Ursprung rechts, left/right werden normalisiert
const enemy = new DOMRectReadOnly(100, 60, -30, 20);

console.log(enemy.left, enemy.right);
console.log(intersects(player, enemy));

70 100 true

ResizeObserver-Eintrag für einen Test nachbauen

const handleResize = (entries) =>
  entries.map(({ contentRect }) => `${contentRect.width}x${contentRect.height}`);

// Nachgebauter Eintrag, wie ihn der ResizeObserver liefern würde
const fakeEntry = { contentRect: new DOMRectReadOnly(0, 0, 320, 240) };
console.log(handleResize([fakeEntry]));

// Serialisierung mit toJSON()
console.log(JSON.stringify(fakeEntry.contentRect));

[ '320x240' ] {"x":0,"y":0,"width":320,"height":240,"top":0,"right":320,"bottom":240,"left":0}

// Wichtig · Fallstricke

Nur lesbar: Wenn Sie etwas zuweisen, passiert außerhalb des Strict Mode nichts. Im Strict Mode wird ein TypeError ausgelöst. Für veränderbare Rechtecke nehmen Sie new DOMRect().
Negative Maße: left/right bzw. top/bottom werden über Math.min/Math.max berechnet. x ist deshalb nicht immer gleich left.
Umwandlung in Zahlen: Nicht numerische Argumente wie "abc" ergeben NaN und werfen keinen Fehler. Prüfen Sie Eingaben deshalb vorher.
Serialisierung: JSON.stringify() ruft toJSON() auf. structuredClone() und postMessage() unterstützen das Objekt ebenfalls.
Kompatibilität: Der Konstruktor ist in allen aktuellen Browsern und in Web Workern verfügbar, im alten Internet Explorer nicht. Node.js bringt DOMRectReadOnly nicht mit. In Tests brauchen Sie dafür z. B. jsdom oder einen Polyfill.

Siehe auch

DOMRectReadOnly DOMRect DOMRectReadOnly.fromRect() Element.prototype.getBoundingClientRect() ResizeObserverEntry.contentRect DOMPointReadOnly new CustomElementRegistry()