Signatur
Beschreibung
Die Eigenschaft naturalWidth eines PerformanceElementTiming-Eintrags gibt die intrinsische Breite der gemessenen Bildressource als vorzeichenlose Ganzzahl in Pixeln zurück. Das ist die tatsächliche Breite der Bilddatei. Sie hängt nicht von CSS, den Attributen width/height oder dem Darstellungsmaßstab ab.
Element-Timing-Einträge entstehen für Elemente mit dem Attribut elementtiming, zum Beispiel <img>, <image> in SVG, Elemente mit CSS-Hintergrundbild oder Textknoten. Bei Bildern enthält naturalWidth die Breite der Bilddatei, bei Text-Einträgen (name === "text-paint") ist der Wert immer 0.
Praktisch ist die Eigenschaft für das Performance-Monitoring: Vergleicht man naturalWidth mit der tatsächlich dargestellten Breite aus intersectionRect oder getBoundingClientRect(), findet man zu große Bilder. Solche Bilder verlängern die Ladezeit (loadTime/renderTime), ohne dass man sie schärfer sieht.
Rückgabewert
0.Beispiele
Intrinsische Bildbreite beobachten
// HTML: <img src="hero.jpg" elementtiming="hero-bild" alt="">
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
console.log(`${entry.identifier}: ${entry.naturalWidth} × ${entry.naturalHeight} px`);
}
});
observer.observe({ type: 'element', buffered: true });Zu große Bilder erkennen
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.naturalWidth === 0) continue; // Text-Eintrag überspringen
const dargestellt = entry.element?.getBoundingClientRect().width ?? entry.intersectionRect.width;
const faktor = entry.naturalWidth / (dargestellt * devicePixelRatio);
if (faktor > 1.5) {
console.warn(
`"${entry.identifier}" ist ${faktor.toFixed(1)}× zu groß ` +
`(${entry.naturalWidth}px geladen, ${Math.round(dargestellt)}px angezeigt)`
);
}
}
});
observer.observe({ type: 'element', buffered: true });Text- und Bild-Einträge unterscheiden
// HTML: <h1 elementtiming="titel">Willkommen</h1>
const observer = new PerformanceObserver((list) => {
list.getEntries().forEach((entry) => {
const art = entry.name === 'text-paint' ? 'Text' : 'Bild';
console.log(art, entry.identifier, 'naturalWidth =', entry.naturalWidth);
});
});
observer.observe({ type: 'element', buffered: true });// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Element Timing API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie nicht. Vorher prüfen:
PerformanceObserver.supportedEntryTypes.includes('element'). - Einträge entstehen nur für Elemente mit dem Attribut
elementtiming. Ohne dieses Attribut liefert der Observer nichts. - Bei Text-Einträgen ist
naturalWidthimmer0. Deshalb nachentry.namefiltern ("image-paint"oder"text-paint"), bevor man rechnet oder durch den Wert teilt. - Der Wert beschreibt die Bilddatei, nicht die Darstellung. Für den Vergleich mit der angezeigten Größe muss man
devicePixelRatioeinrechnen, sonst wirken Bilder für hochauflösende Bildschirme fälschlich zu groß. - Bei Bildern von fremden Ursprüngen ohne
Timing-Allow-Origin-Header istrenderTime0.naturalWidthwird trotzdem gesetzt.