ResizeObserverEntry.contentBoxSize — Eigenschaft · JavaScript-Referenz

Signatur

ResizeObserverEntry.contentBoxSize

Beschreibung

Die schreibgeschützte Eigenschaft contentBoxSize eines ResizeObserverEntry enthält die aktuelle Größe des Inhaltsbereichs (Content-Box) des beobachteten Elements, also ohne Padding, Rahmen und Scrollbalken. Den Wert bekommt man im Callback eines ResizeObserver, sobald sich die Größe des Elements ändert.

Der Wert ist ein Array aus ResizeObserverSize-Objekten mit den Eigenschaften inlineSize und blockSize. Diese Angaben richten sich nach dem Schreibmodus und sind nicht fest an die Achsen gebunden: Bei horizontalem Text (writing-mode: horizontal-tb) ist inlineSize die Breite und blockSize die Höhe. Bei vertikalem Text ist es umgekehrt. Deshalb eignet sich die Eigenschaft gut für Layouts, die mehrere Sprachen und Schreibrichtungen unterstützen.

Dass der Wert ein Array ist, hat einen Grund: Elemente, die in mehrere Fragmente aufgeteilt werden (z. B. bei Mehrspalten-Layouts), sollen künftig eine Größe pro Fragment melden können. Heute enthält das Array in allen Browsern genau einen Eintrag, man greift also mit contentBoxSize[0] darauf zu.

Man verwendet contentBoxSize z. B. für Element-Queries in JavaScript, zum Anpassen der Auflösung eines Canvas, für Diagramme, die ihre Größe an den Container anpassen, oder für Schriftgrößen, die mit dem Container wachsen. Im Vergleich zum älteren contentRect ist es der empfohlene und zukunftssichere Weg.

Rückgabewert

Typ

ReadonlyArray<ResizeObserverSize>

Beschreibung

Ein eingefrorenes Array aus ResizeObserverSize-Objekten. Jedes hat die Eigenschaften inlineSize und blockSize (in CSS-Pixeln, auch Kommazahlen möglich). Derzeit gibt es immer genau einen Eintrag.

Beispiele

Größe der Content-Box auslesen

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

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const [size] = entry.contentBoxSize;
    console.log(`Breite: ${size.inlineSize}px, Höhe: ${size.blockSize}px`);
  }
});

observer.observe(box);

Breite: 320px, Höhe: 180px

Schriftgröße an die Containerbreite anpassen (mit Fallback)

const card = document.querySelector('.card');
const heading = card.querySelector('h2');

const ro = new ResizeObserver((entries) => {
  for (const entry of entries) {
    let width;
    if (entry.contentBoxSize) {
      // Ältere Firefox-Versionen liefern ein einzelnes Objekt statt eines Arrays
      const size = Array.isArray(entry.contentBoxSize)
        ? entry.contentBoxSize[0]
        : entry.contentBoxSize;
      width = size.inlineSize;
    } else {
      width = entry.contentRect.width; // alter Fallback
    }
    heading.style.fontSize = `${Math.max(1, width / 200)}rem`;
  }
});

ro.observe(card);

Responsives Diagramm: Canvas neu zeichnen, wenn sich der Container ändert

const container = document.querySelector('#chart');
const canvas = container.querySelector('canvas');
const ctx = canvas.getContext('2d');

const draw = (w, h) => {
  canvas.width = Math.round(w);
  canvas.height = Math.round(h);
  ctx.fillStyle = '#3b82f6';
  ctx.fillRect(0, h / 2, w, h / 2);
};

const ro = new ResizeObserver(([entry]) => {
  const { inlineSize, blockSize } = entry.contentBoxSize[0];
  // Neu zeichnen erst im nächsten Frame, damit keine Schleifenwarnung entsteht
  requestAnimationFrame(() => draw(inlineSize, blockSize));
});

ro.observe(container);

// Später aufräumen:
// ro.disconnect();

// Wichtig · Fallstricke

Immer ein Array: Schreibt man entry.contentBoxSize.inlineSize, bekommt man undefined. Richtig ist entry.contentBoxSize[0].inlineSize.
Alte Firefox-Versionen (69–91) lieferten ein einzelnes ResizeObserverSize-Objekt statt eines Arrays. Wer diese Versionen unterstützen muss, prüft mit Array.isArray(). Noch ältere Browser kennen contentBoxSize gar nicht; dort bleibt nur contentRect.
Logische Größen: inlineSize und blockSize sind nicht immer Breite und Höhe. Bei vertikalem writing-mode sind sie vertauscht.
Nur Inhalt: Padding und Rahmen sind nicht enthalten. Für die Außenmaße nimmt man borderBoxSize, für echte Gerätepixel (z. B. bei Canvas auf HiDPI-Bildschirmen) devicePixelContentBoxSize.
Schleifen vermeiden: Ändert man im Callback die Größe des beobachteten Elements, kann das den Fehler ResizeObserver loop completed with undelivered notifications auslösen. Änderungen am Layout legt man deshalb am besten in requestAnimationFrame oder vergleicht vorher mit dem letzten Wert.
Die Werte sind CSS-Pixel und können Kommazahlen sein. Vor dem Setzen von Canvas-Maßen sollte man runden.

Siehe auch

IntersectionObserverEntry.boundingClientRect ResizeObserverEntry.borderBoxSize ResizeObserverEntry.contentRect ResizeObserverEntry.devicePixelContentBoxSize ResizeObserverEntry.target