ResizeObserverSize.inlineSize — Eigenschaft · JavaScript-Referenz

Signatur

ResizeObserverSize.inlineSize

Beschreibung

Die schreibgeschützte Eigenschaft inlineSize eines ResizeObserverSize-Objekts gibt die Größe des beobachteten Elements in der Inline-Dimension an. Das ist die Richtung, in der Text innerhalb einer Zeile läuft. Bei horizontalen Schreibrichtungen wie Deutsch oder Englisch (writing-mode: horizontal-tb) entspricht sie der Breite. Bei vertikalen Schreibrichtungen (vertical-rl, vertical-lr) entspricht sie der Höhe.

Welche Box gemessen wird, hängt davon ab, über welche Eigenschaft von ResizeObserverEntry Sie das Objekt abrufen:

entry.borderBoxSize: Border-Box, also Inhalt, Innenabstand (Padding) und Rahmen, in CSS-Pixeln.
entry.contentBoxSize: nur der Inhaltsbereich ohne Padding und Rahmen, in CSS-Pixeln.
entry.devicePixelContentBoxSize: Inhaltsbereich in physischen Gerätepixeln. Ideal für pixelgenaue <canvas>-Darstellung.

Diese drei Eigenschaften sind jeweils ein Array von ResizeObserverSize-Objekten. So lassen sich später auch fragmentierte Elemente abbilden, etwa bei mehrspaltigem Layout. Derzeit enthält das Array praktisch immer genau einen Eintrag, deshalb greift man üblicherweise mit [0].inlineSize zu.

Verwenden Sie inlineSize statt contentRect.width, wenn Ihr Code mehrere Schreibrichtungen unterstützen soll oder wenn Sie gezielt die Border-Box bzw. Gerätepixel brauchen. Typische Einsatzfälle sind Komponenten, die sich an ihre Container-Größe anpassen, responsive Diagramme und scharfe Canvas-Grafiken auf HiDPI-Bildschirmen.

Rückgabewert

Typ

number

Beschreibung

Größe in der Inline-Dimension als Gleitkommazahl. Die Einheit sind CSS-Pixel bei borderBoxSize und contentBoxSize bzw. Gerätepixel (ganzzahlig) bei devicePixelContentBoxSize.

Beispiele

Breite der Border-Box beobachten

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

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

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

Border-Box: 320 × 180 px

Komponente per Container-Breite umschalten

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

const ro = new ResizeObserver(([entry]) => {
  // Inhaltsbreite ohne Padding und Rahmen
  const width = entry.contentBoxSize[0].inlineSize;
  widget.classList.toggle('widget--compact', width < 400);
  widget.classList.toggle('widget--wide', width >= 800);
});

ro.observe(widget);

Scharfes Canvas auf HiDPI-Displays

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

const ro = new ResizeObserver(([entry]) => {
  let width, height;
  if (entry.devicePixelContentBoxSize) {
    // Exakte Gerätepixel, keine Rundungsfehler
    width = entry.devicePixelContentBoxSize[0].inlineSize;
    height = entry.devicePixelContentBoxSize[0].blockSize;
  } else {
    // Ersatzlösung, z. B. für Safari
    width = Math.round(entry.contentBoxSize[0].inlineSize * devicePixelRatio);
    height = Math.round(entry.contentBoxSize[0].blockSize * devicePixelRatio);
  }
  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, { box: 'content-box' });
}

Vertikale Schreibrichtung: inlineSize ist die Höhe

const el = document.querySelector('.vertical');
el.style.writingMode = 'vertical-rl';
el.style.width = '100px';
el.style.height = '300px';

new ResizeObserver(([entry]) => {
  const size = entry.contentBoxSize[0];
  console.log('inlineSize:', size.inlineSize); // Höhe
  console.log('blockSize:', size.blockSize);   // Breite
}).observe(el);

inlineSize: 300 blockSize: 100

// Wichtig · Fallstricke

Logische statt physische Dimension: inlineSize ist nicht immer die Breite. Bei writing-mode: vertical-* steht dort die Höhe. Wer ausdrücklich die physische Breite braucht, muss die Schreibrichtung prüfen oder contentRect.width verwenden.
Array statt Objekt: Ältere Firefox-Versionen (vor 92) lieferten für contentBoxSize bzw. borderBoxSize ein einzelnes Objekt statt eines Arrays. Wenn Sie sehr alte Browser unterstützen müssen, prüfen Sie das mit Array.isArray(entry.contentBoxSize).
devicePixelContentBoxSize wird von Safari bislang nicht unterstützt. Prüfen Sie deshalb vorher, ob die Eigenschaft vorhanden ist, und sehen Sie eine Ersatzlösung mit devicePixelRatio vor.
Der Wert ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert bzw. führt im Strict Mode zu einem TypeError.
Wenn Sie im Callback die Größe des beobachteten Elements ändern, kann eine Endlosschleife entstehen. Der Browser meldet dann den Fehler ResizeObserver loop completed with undelivered notifications.
Die Werte sind Gleitkommazahlen, z. B. 312.5. Runden Sie sie bei Bedarf, bevor Sie sie etwa als Canvas-Größe verwenden.

Siehe auch

PressureObserver.knownSources ResizeObserverSize.blockSize ResizeObserverEntry.contentBoxSize ResizeObserverEntry.borderBoxSize ResizeObserverEntry.contentRect