ResizeObserverSize — Schnittstelle · JavaScript-Referenz

Signatur

interface ResizeObserverSize

Beschreibung

ResizeObserverSize ist ein reines Datenobjekt der Resize Observer API. Es gibt keinen Konstruktor. Instanzen erhältst du nur über die Eigenschaften contentBoxSize, borderBoxSize und devicePixelContentBoxSize eines ResizeObserverEntry. Jede dieser Eigenschaften ist ein Array mit ResizeObserverSize-Objekten. Heute steht darin in der Regel genau ein Element (Index 0). Mehrere Einträge sind für fragmentierte Elemente vorgesehen, etwa bei mehrspaltigem Layout.

Das Objekt hat zwei schreibgeschützte Eigenschaften:

inlineSize: die Länge in Inline-Richtung, also in Textrichtung. Bei horizontalem Schreibmodus ist das die Breite.
blockSize: die Länge in Block-Richtung, also quer zur Textrichtung. Bei horizontalem Schreibmodus ist das die Höhe.

Die Angaben beziehen sich auf logische Richtungen und nicht auf physische. Deshalb berücksichtigen sie Schreibmodi wie writing-mode: vertical-rl automatisch: Dort entspricht inlineSize der Höhe. Für Komponenten, die sich an ihren Container anpassen (Diagramme, Canvas, virtuelle Listen, Container-abhängige Layouts), ist das zuverlässiger als das ältere contentRect.

Die Werte sind CSS-Pixel als Gleitkommazahlen. Eine Ausnahme ist devicePixelContentBoxSize: Dort stehen echte Geräte-Pixel. Das ist wichtig, wenn ein Canvas pixelgenau gerendert werden soll.

Parameter

Name	Typ	Default	Beschreibung
$inlineSize	number		Schreibgeschützte Eigenschaft: Länge der Box in Inline-Richtung (bei horizontalem Text die Breite), in CSS-Pixeln bzw. bei `devicePixelContentBoxSize` in Geräte-Pixeln.
$blockSize	number		Schreibgeschützte Eigenschaft: Länge der Box in Block-Richtung (bei horizontalem Text die Höhe).

Rückgabewert

Typ

ResizeObserverSize

Beschreibung

Ein Objekt mit den schreibgeschützten Zahlen inlineSize und blockSize. Es steckt in den Arrays entry.contentBoxSize, entry.borderBoxSize und entry.devicePixelContentBoxSize.

Beispiele

Inhalts- und Rahmengröße eines Elements auslesen

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

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    // Jede Box-Eigenschaft ist ein Array von ResizeObserverSize-Objekten
    const [content] = entry.contentBoxSize;
    const [border] = entry.borderBoxSize;
    console.log(`Inhalt: ${content.inlineSize} × ${content.blockSize}`);
    console.log(`Mit Rahmen: ${border.inlineSize} × ${border.blockSize}`);
  }
});

observer.observe(box);

Inhalt: 300 × 150 Mit Rahmen: 322 × 172

Canvas pixelgenau an Geräte-Pixel anpassen

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

const observer = new ResizeObserver(([entry]) => {
  let width, height;
  if (entry.devicePixelContentBoxSize) {
    // Echte Geräte-Pixel, ohne Rundungsfehler
    ({ inlineSize: width, blockSize: height } = entry.devicePixelContentBoxSize[0]);
  } else {
    // Ersatzlösung, z. B. für Safari
    const size = entry.contentBoxSize[0];
    width = Math.round(size.inlineSize * devicePixelRatio);
    height = Math.round(size.blockSize * devicePixelRatio);
  }
  canvas.width = width;
  canvas.height = height;
  ctx.fillStyle = 'teal';
  ctx.fillRect(0, 0, width, height);
});

// Für devicePixelContentBoxSize muss die Box explizit angegeben werden
try {
  observer.observe(canvas, { box: 'device-pixel-content-box' });
} catch {
  observer.observe(canvas);
}

Container-abhängiges Layout mit Fallback für alte Browser

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

const getInlineSize = (entry) => {
  const size = entry.contentBoxSize;
  if (size) {
    // Alte Firefox-Versionen lieferten ein einzelnes Objekt statt eines Arrays
    return Array.isArray(size) ? size[0].inlineSize : size.inlineSize;
  }
  return entry.contentRect.width;
};

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const width = getInlineSize(entry);
    entry.target.classList.toggle('card--wide', width >= 480);
    console.log(`Breite: ${width}px, breit: ${width >= 480}`);
  }
});

observer.observe(card);

Breite: 520px, breit: true

// Wichtig · Fallstricke

Logisch statt physisch: inlineSize ist nicht immer die Breite. Bei writing-mode: vertical-* tauschen inlineSize und blockSize ihre Bedeutung.
Array statt Objekt: contentBoxSize und borderBoxSize sind Arrays, also [0] nicht vergessen. Firefox vor Version 92 lieferte ein einzelnes Objekt. Falls alte Browser unterstützt werden müssen, beides abfangen.
devicePixelContentBoxSize: Diese Eigenschaft wird nur befüllt, wenn du mit { box: 'device-pixel-content-box' } beobachtest. Safari unterstützt sie derzeit nicht, also eine Ersatzlösung mit devicePixelRatio vorsehen.
Kein Konstruktor: new ResizeObserverSize() wirft einen TypeError. Die Werte sind schreibgeschützt.
Endlosschleifen vermeiden: Wenn du im Callback die Größe des beobachteten Elements selbst änderst, kann das Fehler wie „ResizeObserver loop completed with undelivered notifications“ auslösen.
Die Werte sind Gleitkommazahlen, z. B. 150.5. Wenn du sie als Canvas-Attribute setzt, vorher runden.

Siehe auch

ResizeObserverEntry ResizeObserver PressureObserver ReportingObserver FileSystemObserver