HTMLImageElement.naturalWidth — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.naturalWidth

Beschreibung

Die schreibgeschützte Eigenschaft naturalWidth liefert die natürliche Breite eines Bildes: die Breite, die das Bild hätte, wenn es ohne jede Größenvorgabe durch CSS oder durch die Attribute width/height dargestellt würde. Der Wert ist dichtekorrigiert. Wird ein 800 Pixel breites Bild zum Beispiel über srcset mit dem Deskriptor 2x ausgewählt, meldet naturalWidth den Wert 400.

Das Gegenstück ist HTMLImageElement.width. Diese Eigenschaft gibt die dargestellte Breite zurück, also die Breite nach Anwendung von Attributen und CSS. Mit naturalWidth und naturalHeight kannst du das echte Seitenverhältnis berechnen, prüfen, ob ein Bild hochskaliert und damit unscharf dargestellt wird, oder Mindestauflösungen bei Bild-Uploads kontrollieren.

Einen sinnvollen Wert gibt es erst, wenn das Bild geladen ist. Bis dahin und bei defekten Bildern ist der Wert 0. Lies naturalWidth deshalb im load-Ereignis aus oder nach await img.decode(). Alternativ prüfst du vorher img.complete.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl (unsigned long) mit der natürlichen Breite in CSS-Pixeln. Der Wert ist 0, solange das Bild nicht geladen ist, wenn es fehlerhaft ist oder keine intrinsische Breite hat.

Beispiele

Natürliche und dargestellte Breite vergleichen

const img = document.querySelector('#produktbild');

const pruefeSkalierung = () => {
  console.log(`Natürlich: ${img.naturalWidth}px, dargestellt: ${img.width}px`);
  if (img.width > img.naturalWidth) {
    console.warn('Bild wird hochskaliert und wirkt ggf. unscharf.');
  }
};

// Bereits geladen (z. B. aus dem Cache)? Sonst auf load warten.
if (img.complete && img.naturalWidth > 0) {
  pruefeSkalierung();
} else {
  img.addEventListener('load', pruefeSkalierung, { once: true });
}

Natürlich: 640px, dargestellt: 1200px Bild wird hochskaliert und wirkt ggf. unscharf.

Bildmaße vorab mit decode() ermitteln

const ladeBildmasse = async (url) => {
  const img = new Image();
  img.src = url;
  await img.decode(); // wirft einen Fehler, wenn das Bild nicht dekodiert werden kann
  return {
    breite: img.naturalWidth,
    hoehe: img.naturalHeight,
    verhaeltnis: img.naturalWidth / img.naturalHeight
  };
};

const masse = await ladeBildmasse('/bilder/panorama.jpg');
console.log(masse);

{ breite: 3000, hoehe: 1000, verhaeltnis: 3 }

Mindestbreite beim Bild-Upload prüfen

const input = document.querySelector('input[type=file]');

input.addEventListener('change', async () => {
  const datei = input.files[0];
  if (!datei) return;

  const url = URL.createObjectURL(datei);
  const img = new Image();
  img.src = url;

  try {
    await img.decode();
    if (img.naturalWidth < 1024) {
      alert(`Bild zu klein: ${img.naturalWidth}px (mind. 1024px)`);
    } else {
      console.log('Bild akzeptiert:', img.naturalWidth, 'px breit');
    }
  } catch {
    alert('Datei ist kein gültiges Bild.');
  } finally {
    URL.revokeObjectURL(url); // Speicher freigeben
  }
});

Bild akzeptiert: 2048 px breit

Defekte Bilder auf der Seite finden

window.addEventListener('load', () => {
  const defekt = [...document.images].filter(
    (img) => img.complete && img.naturalWidth === 0
  );
  console.log(`${defekt.length} defekte Bilder:`, defekt.map((i) => i.src));
});

1 defekte Bilder: ["https://example.com/fehlt.png"]

// Wichtig · Fallstricke

Zuverlässig erst nach dem Laden: Vor dem load-Ereignis ist der Wert 0. Auch complete === true reicht allein nicht aus, denn bei defekten Bildern ist complete ebenfalls true und naturalWidth gleich 0. Prüfe deshalb beide Werte.
Dichtekorrektur: Bei srcset mit x-Deskriptoren teilt der Browser die Pixelbreite der Datei durch die Pixeldichte. Die echte Pixelbreite der Datei bekommst du daher nicht immer über naturalWidth. Bei w-Deskriptoren kann das Ergebnis außerdem vom gewählten Kandidaten und von sizes abhängen.
SVG-Bilder: Hat eine SVG-Datei keine Attribute width/height, sondern nur eine viewBox, liefern die Browser unterschiedliche Werte, zum Beispiel 0 oder einen Standardwert wie 300×150.
EXIF-Ausrichtung: Moderne Browser berücksichtigen die EXIF-Ausrichtung (image-orientation: from-image). Bei hochkant gedrehten Fotos können Breite und Höhe deshalb gegenüber den Rohdaten der Datei vertauscht sein.
Schreibgeschützt: Zuweisungen werden ignoriert; im strikten Modus löst eine Zuweisung einen TypeError aus.
Kompatibilität: Wird von allen modernen Browsern unterstützt, im Internet Explorer ab Version 9.

Siehe auch

HTMLImageElement.naturalHeight HTMLImageElement.width HTMLImageElement.complete HTMLImageElement.decode() HTMLImageElement HTMLVideoElement.videoWidth