Signatur
Beschreibung
Die Eigenschaft blockSize eines ResizeObserverSize-Objekts enthält die Größe des beobachteten Elements in der Block-Dimension, also senkrecht zur Textrichtung. Ein ResizeObserverSize-Objekt findet man in den Arrays contentBoxSize, borderBoxSize und devicePixelContentBoxSize eines ResizeObserverEntry. Welcher Kasten gemessen wird, hängt also davon ab, aus welchem dieser Arrays der Wert stammt: Inhaltskasten, Rahmenkasten (mit Innenabstand und Rahmen) oder Inhaltskasten in echten Gerätepixeln.
Weil die Eigenschaft logisch statt physisch definiert ist, passt sie sich an writing-mode an. In horizontalen Schreibrichtungen wie horizontal-tb (Deutsch, Englisch) entspricht blockSize der Höhe. In vertikalen Schreibrichtungen wie vertical-rl (z. B. traditionelles Japanisch) entspricht sie der Breite. Das Gegenstück dazu ist inlineSize.
Typische Einsatzfälle sind Komponenten, die sich an ihre eigene Größe anpassen (Container-abhängige Layouts), automatisch wachsende Textfelder, virtuelle Listen mit unterschiedlich hohen Zeilen und scharf dargestellte <canvas>-Grafiken, deren Pufferauflösung zu den Gerätepixeln passen soll.
Rückgabewert
contentBoxSize und borderBoxSize und Gerätepixel (Ganzzahl) bei devicePixelContentBoxSize.Beispiele
Höhe eines Elements über den Inhaltskasten beobachten
const box = document.querySelector('#panel');
const observer = new ResizeObserver((entries) => {
for (const entry of entries) {
// contentBoxSize ist ein Array; bei normalen Elementen gibt es genau einen Eintrag
const { blockSize, inlineSize } = entry.contentBoxSize[0];
console.log(`Höhe: ${blockSize}px, Breite: ${inlineSize}px`);
}
});
observer.observe(box);Rahmenkasten und Schreibrichtung vergleichen
const el = document.querySelector('.vertical-text');
el.style.writingMode = 'vertical-rl';
new ResizeObserver(([entry]) => {
const border = entry.borderBoxSize[0];
const rect = entry.target.getBoundingClientRect();
// In vertikaler Schreibrichtung entspricht blockSize der Breite
console.log('blockSize:', border.blockSize);
console.log('physische Breite:', rect.width);
}).observe(el, { box: 'border-box' });Canvas-Puffer passend zu den Gerätepixeln
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const ro = new ResizeObserver(([entry]) => {
// Fallback für Browser ohne devicePixelContentBoxSize (z. B. Safari)
const size = entry.devicePixelContentBoxSize?.[0];
const dpr = window.devicePixelRatio;
const height = size ? size.blockSize : Math.round(entry.contentBoxSize[0].blockSize * dpr);
const width = size ? size.inlineSize : Math.round(entry.contentBoxSize[0].inlineSize * dpr);
canvas.width = width;
canvas.height = height;
ctx.fillStyle = '#0a7';
ctx.fillRect(0, 0, width, height / 2);
console.log(`Canvas-Puffer: ${width}×${height}`);
});
ro.observe(canvas, { box: 'device-pixel-content-box' });// Wichtig · Fallstricke
- Logisch, nicht physisch:
blockSizeist nur bei horizontaler Schreibrichtung die Höhe. Wenn du wirklich die Höhe brauchst, egal wie die Schreibrichtung ist, prüfegetComputedStyle(el).writingModeoder nutzeentry.contentRect.height. - Array statt Objekt:
contentBoxSizeundborderBoxSizesind Arrays. Greife daher immer mit[0]zu. Firefox vor Version 92 lieferte ein einzelnes Objekt. Wer diese alten Versionen unterstützen muss, fragt mitArray.isArray()ab. - Kommazahlen: Die Werte in CSS-Pixeln können Nachkommastellen haben, z. B. bei Zoom oder
rem-Angaben. Runde sie, bevor du sie etwa als Canvas-Größe verwendest. devicePixelContentBoxSizegibt es in Chromium und Firefox. Safari unterstützt es bisher nicht, deshalb brauchst du dort einen Fallback.- Endlosschleifen: Wenn du im Callback die Größe des beobachteten Elements änderst, kann das die Warnung „ResizeObserver loop completed with undelivered notifications“ auslösen. Ändere die Größe nur, wenn sich der Wert wirklich geändert hat.
- SVG-Elemente ohne CSS-Box und Elemente mit
display: nonemelden0.