ResizeObserverEntry — Schnittstelle · JavaScript-Referenz

Signatur

interface ResizeObserverEntry

Beschreibung

Ein ResizeObserverEntry wird nie selbst erzeugt. Der Browser legt die Objekte an und übergibt sie als Array (entries) an die Rückruffunktion eines ResizeObserver. Jeder Eintrag steht für genau ein überwachtes Element, dessen Größe sich seit der letzten Meldung geändert hat.

Das Interface hat folgende schreibgeschützte Eigenschaften:

target – das überwachte Element bzw. SVGElement.
contentRect – ein DOMRectReadOnly mit der Größe der Inhaltsbox (ohne Padding und Rahmen). Das ist die ältere Schnittstelle, die aus Kompatibilitätsgründen erhalten bleibt.
contentBoxSize – ein Array von ResizeObserverSize-Objekten mit inlineSize und blockSize der Inhaltsbox.
borderBoxSize – wie oben, aber für die Rahmenbox (inklusive Padding und Rahmen).
devicePixelContentBoxSize – Größe der Inhaltsbox in echten Gerätepixeln. Das ist wichtig für pixelgenaues Zeichnen auf einem <canvas>.

Die *BoxSize-Eigenschaften arbeiten mit logischen Maßen: inlineSize entspricht bei horizontaler Schreibrichtung der Breite, blockSize der Höhe. Bei vertikaler Schreibrichtung (writing-mode: vertical-rl) ist es umgekehrt. Sie sind Arrays, damit später auch fragmentierte Elemente (z. B. in mehreren Spalten) abgebildet werden können. Derzeit enthalten sie immer genau ein Element, das Sie über [0] abrufen.

Rückgabewert

Typ

ResizeObserverEntry

Beschreibung

Wird nicht direkt zurückgegeben, sondern als Element des entries-Arrays an die Rückruffunktion von ResizeObserver übergeben.

Beispiele

Grundlagen: Größe eines Elements auslesen

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

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const { inlineSize, blockSize } = entry.contentBoxSize[0];
    console.log(`${entry.target.className}: ${inlineSize}×${blockSize}px`);
  }
});

observer.observe(box);

box: 300×150px

Responsive Komponente: Layout nach Containerbreite umschalten

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

const ro = new ResizeObserver(([entry]) => {
  // borderBoxSize enthält Padding und Rahmen
  const width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
  entry.target.classList.toggle('card--compact', width < 400);
  entry.target.classList.toggle('card--wide', width >= 800);
});

ro.observe(card, { box: 'border-box' });

Canvas pixelgenau an Gerätepixel anpassen

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

const ro = new ResizeObserver(([entry]) => {
  let width, height;
  if (entry.devicePixelContentBoxSize) {
    ({ inlineSize: width, blockSize: height } = entry.devicePixelContentBoxSize[0]);
  } else {
    // Fallback für Safari
    const dpr = window.devicePixelRatio;
    width = Math.round(entry.contentBoxSize[0].inlineSize * dpr);
    height = Math.round(entry.contentBoxSize[0].blockSize * dpr);
  }
  canvas.width = width;
  canvas.height = height;
  ctx.fillStyle = 'teal';
  ctx.fillRect(0, 0, width / 2, height / 2);
});

try {
  ro.observe(canvas, { box: 'device-pixel-content-box' });
} catch {
  ro.observe(canvas);
}

Mehrere Elemente mit einem Observer überwachen

const panels = document.querySelectorAll('.panel');

const ro = new ResizeObserver((entries) => {
  entries.forEach(({ target, contentRect }) => {
    target.dataset.size = `${Math.round(contentRect.width)}px`;
  });
});

panels.forEach((panel) => ro.observe(panel));

// Später aufräumen, z. B. beim Entfernen der Komponente
// ro.disconnect();

// Wichtig · Fallstricke

Arrays bei *BoxSize: contentBoxSize, borderBoxSize und devicePixelContentBoxSize sind Arrays. Ältere Firefox-Versionen (vor 92) lieferten stattdessen ein einzelnes Objekt. Wenn Sie diese Versionen noch unterstützen müssen, prüfen Sie mit Array.isArray().
devicePixelContentBoxSize fehlt in Safari. Prüfen Sie die Eigenschaft deshalb vor der Nutzung und rechnen Sie ersatzweise mit window.devicePixelRatio.
Endlosschleifen: Wenn Sie im Rückruf die Größe des überwachten Elements ändern, kann das neue Meldungen auslösen. Der Browser bricht dann mit „ResizeObserver loop completed with undelivered notifications“ ab. Ändern Sie Größen nur, wenn es wirklich nötig ist, oder verschieben Sie die Änderung mit requestAnimationFrame.
contentRect enthält weder Padding noch Rahmen. Seine Werte x/y entsprechen dem Padding und geben nicht die Position auf der Seite an. Für Positionen verwenden Sie getBoundingClientRect().
Rein visuelle CSS-Transformationen (transform: scale()) lösen keinen Eintrag aus, weil sie die Layoutgröße nicht verändern.
Direkt nach observe() wird immer ein erster Eintrag gemeldet, auch ohne Größenänderung.

Siehe auch

ResizeObserverSize ResizeObserver IntersectionObserverEntry PressureObserver FileSystemEntry