DOMRectReadOnly.width — Eigenschaft · JavaScript-Referenz

Signatur

get DOMRectReadOnly.prototype.width

Beschreibung

Die schreibgeschützte Eigenschaft width gibt die Breite eines Rechtecks als Gleitkommazahl in CSS-Pixeln zurück. DOMRectReadOnly ist die Basis von DOMRect. Deshalb gibt es die Eigenschaft auf allen Rechteck-Objekten, die zum Beispiel Element.getBoundingClientRect(), Element.getClientRects(), Range.getBoundingClientRect() oder ResizeObserverEntry.contentRect zurückgeben.

Ein Rechteck wird intern durch Ursprung (x, y) und Ausdehnung (width, height) beschrieben. Die Ausdehnung darf negativ sein: Dann liegt der Ursprung auf der rechten Seite. Die abgeleiteten Eigenschaften left und right werden dagegen immer normalisiert, also left = min(x, x + width) und right = max(x, x + width).

Bei getBoundingClientRect() steht width für die Breite der sichtbaren Rahmenbox (Inhalt + Innenabstand + Rahmen), und zwar nach CSS-Transformationen. Deshalb unterscheidet sich der Wert oft von offsetWidth: offsetWidth ist ganzzahlig gerundet und ignoriert Transformationen.

Weil die Eigenschaft schreibgeschützt ist, wird eine Zuweisung im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Für ein veränderbares Rechteck nimmt man DOMRect. Dort ist width beschreibbar.

Rückgabewert

Typ

number

Beschreibung

Breite des Rechtecks in CSS-Pixeln als Gleitkommazahl (double). Kann 0, negativ oder ein Bruchteil sein.

Beispiele

Rechteck erzeugen und Breite auslesen

const rect = new DOMRectReadOnly(10, 20, 150, 80);
console.log(rect.width);  // 150
console.log(rect.right);  // 160 (x + width)

150 160

Negative Breite und normalisierte Kanten

const rect = DOMRectReadOnly.fromRect({ x: 100, y: 0, width: -40, height: 20 });
console.log(rect.width);  // -40
console.log(rect.left);   // 60
console.log(rect.right);  // 100
// Echte Breite unabhängig vom Vorzeichen:
console.log(Math.abs(rect.width)); // 40

-40 60 100 40

Gerenderte Breite eines Elements (inkl. Transformation)

const box = document.querySelector('#card');
box.style.transform = 'scale(1.5)';

const { width } = box.getBoundingClientRect();
console.log(`Gerendert: ${width}px, offsetWidth: ${box.offsetWidth}px`);

Gerendert: 300px, offsetWidth: 200px

Breitenänderungen mit ResizeObserver verfolgen

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

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const w = entry.contentRect.width; // DOMRectReadOnly
    panel.classList.toggle('kompakt', w < 400);
    console.log(`Inhaltsbreite: ${w.toFixed(1)}px`);
  }
});

observer.observe(panel);

Inhaltsbreite: 523.5px

// Wichtig · Fallstricke

Schreibgeschützt: rect.width = 10 hat bei DOMRectReadOnly keine Wirkung. Im strikten Modus wirft die Zuweisung einen TypeError. Wer Werte ändern will, erzeugt ein DOMRect.
Negative Werte: Bei selbst erzeugten Rechtecken kann width negativ sein. Für die tatsächliche Ausdehnung nimmt man Math.abs(rect.width) oder rect.right - rect.left.
Box-Modell: getBoundingClientRect().width enthält Innenabstand und Rahmen. ResizeObserverEntry.contentRect.width enthält nur die Inhaltsbox.
Performance: Wer width über getBoundingClientRect() liest, kann ein synchrones Layout erzwingen („Layout Thrashing“). Lese- und Schreibzugriffe aufs DOM besser bündeln oder ResizeObserver verwenden.
Nicht sichtbare Elemente: Elemente mit display: none liefern die Breite 0.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Konstruktor new DOMRectReadOnly() fehlt in alten Edge-Versionen (EdgeHTML) und im Internet Explorer. Dort liefert getBoundingClientRect() ein ClientRect, das keine Eigenschaften x und y hat.

Siehe auch

DOMRectReadOnly DOMRectReadOnly.height DOMRectReadOnly.x DOMRectReadOnly.right DOMRect Element.getBoundingClientRect() ResizeObserver