DOMRect.x — Eigenschaft · JavaScript-Referenz

Signatur

DOMRect.x

Beschreibung

Die Eigenschaft x eines DOMRect gibt die horizontale Koordinate des Ursprungs des Rechtecks in CSS-Pixeln an. Bei Rechtecken aus Element.getBoundingClientRect() ist das der Abstand vom linken Rand des Viewports. Scrollt die Seite horizontal, ändert sich der Wert also.

Im Unterschied zu DOMRectReadOnly ist x bei DOMRect beschreibbar. Setzt man den Wert, verschiebt sich das Rechteck. width bleibt dabei gleich, left und right werden daraus neu berechnet.

Wichtig: x ist nicht immer dasselbe wie left. Ist width negativ, liegt der Ursprung am rechten Rand. left ist dann x + width, und x entspricht right. Werte aus getBoundingClientRect() haben nie eine negative Breite, dort sind x und left gleich.

Typische Einsatzfälle sind: Tooltips und Popover positionieren, Kollisionen erkennen, Mausposition relativ zu einem Element berechnen und Layout-Messungen für Animationen (FLIP-Technik).

Rückgabewert

Typ

number

Beschreibung

Gleitkommazahl mit der x-Koordinate des Ursprungs in CSS-Pixeln. Kann negativ oder ein Bruchwert sein. Beim Setzen wird der Wert in eine number umgewandelt (unrestricted double, also auch NaN und Infinity).

Beispiele

Horizontale Position eines Elements im Viewport auslesen

const box = document.querySelector('#box');
const rect = box.getBoundingClientRect();

console.log(`Abstand zum linken Viewport-Rand: ${rect.x}px`);
// Absolute Position im Dokument (inkl. Scroll)
console.log(`Position im Dokument: ${rect.x + window.scrollX}px`);

Abstand zum linken Viewport-Rand: 120px Position im Dokument: 120px

Eigenes DOMRect erzeugen und x verschieben

const rect = new DOMRect(10, 20, 100, 50);
console.log(rect.x, rect.left, rect.right); // 10 10 110

rect.x = 40; // Rechteck um 30px nach rechts verschieben
console.log(rect.x, rect.left, rect.right, rect.width);

10 10 110 40 40 140 100

Unterschied zwischen x und left bei negativer Breite

const rect = new DOMRect(200, 0, -50, 30);

console.log('x:', rect.x);       // Ursprung
console.log('left:', rect.left); // min(x, x + width)
console.log('right:', rect.right);

x: 200 left: 150 right: 200

Mausposition relativ zu einem Canvas berechnen

const canvas = document.querySelector('canvas');

canvas.addEventListener('pointerdown', (event) => {
  const { x, y } = canvas.getBoundingClientRect();
  const localX = event.clientX - x;
  const localY = event.clientY - y;
  console.log(`Klick bei (${localX.toFixed(1)}, ${localY.toFixed(1)})`);
});

Klick bei (42.5, 17.0)

// Wichtig · Fallstricke

Bezug zum Viewport: Werte aus getBoundingClientRect() hängen vom Scrollen ab. Für Koordinaten im Dokument muss man window.scrollX addieren.
x vs. left: Bei negativer Breite unterscheiden sich die beiden Werte. Für die sichtbare linke Kante ist left die sicherere Wahl.
Schreibzugriff: Das Setzen von x auf einem gemessenen Rechteck ändert nur das Objekt, nicht das Element im DOM. Bei DOMRectReadOnly, etwa ResizeObserverEntry.contentRect, ist x schreibgeschützt. Eine Zuweisung wird dort ohne Fehler ignoriert, im Strict Mode wirft sie einen TypeError.
Transformationen: getBoundingClientRect() berücksichtigt CSS-Transforms. x beschreibt dann das umschließende Rechteck, nicht die ursprüngliche Box.
Performance: Jede Messung kann ein synchrones Layout (Reflow) auslösen. Messungen sollten gebündelt werden und nicht mit DOM-Änderungen abwechseln.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Der alte Internet Explorer kannte bei ClientRect nur left, aber kein x.

Siehe auch

DOMRect.y DOMRect.width DOMRectReadOnly.left DOMRect DOMRectReadOnly Element.getBoundingClientRect() CSSRotate.z