HTMLImageElement.naturalHeight — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLImageElement.naturalHeight

Beschreibung

Die schreibgeschützte Eigenschaft naturalHeight gibt die natürliche Höhe eines Bildes zurück. Gemeint ist die Höhe, die das Bild ohne Vorgaben durch CSS, das Attribut height oder das umgebende Layout hätte. Bei Rastergrafiken wie JPEG, PNG oder WebP entspricht das normalerweise der Pixelhöhe der Datei, korrigiert um die Bilddichte. Wählt der Browser über srcset etwa eine 2x-Variante mit 800 Pixeln Höhe, meldet naturalHeight nur 400.

Man braucht die Eigenschaft vor allem, wenn man das Seitenverhältnis oder die Originalgröße eines Bildes wissen muss, zum Beispiel für Lightboxen, Bildzuschnitte, Canvas-Verarbeitung, Upload-Vorschauen oder um vor dem Hochladen die Mindestauflösung zu prüfen. Das Gegenstück ist naturalWidth. Die Eigenschaft height gibt dagegen die dargestellte Höhe zurück.

Einen sinnvollen Wert gibt es erst, wenn das Bild geladen oder zumindest dekodiert ist. Solange die Bilddaten fehlen, das Laden fehlgeschlagen ist oder das Bild keine intrinsische Höhe hat, ist der Wert 0. Man liest die Eigenschaft deshalb im load-Ereignis aus, nach await img.decode() oder nachdem man mit img.complete geprüft hat, ob das Bild fertig geladen ist.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl ohne Vorzeichen: die intrinsische, dichtekorrigierte Höhe in CSS-Pixeln. Der Wert ist 0, wenn das Bild noch nicht geladen ist, nicht geladen werden konnte oder keine intrinsische Höhe hat.

Beispiele

Natürliche und dargestellte Höhe vergleichen

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

const ausgeben = () => {
  console.log(`Natürlich: ${img.naturalWidth}×${img.naturalHeight}`);
  console.log(`Dargestellt: ${img.width}×${img.height}`);
};

// Wurde das Bild schon aus dem Cache geladen, ist complete bereits true
if (img.complete && img.naturalHeight > 0) {
  ausgeben();
} else {
  img.addEventListener('load', ausgeben, { once: true });
}

Natürlich: 1920×1080 Dargestellt: 480×270

Bildmaße asynchron mit decode() ermitteln

const ladeBildMasse = async (url) => {
  const img = new Image();
  img.src = url;
  await img.decode(); // wird abgelehnt, wenn das Bild nicht geladen werden kann
  return {
    breite: img.naturalWidth,
    hoehe: img.naturalHeight,
    verhaeltnis: +(img.naturalWidth / img.naturalHeight).toFixed(3)
  };
};

ladeBildMasse('/bilder/panorama.jpg')
  .then((masse) => console.log(masse))
  .catch(() => console.error('Bild konnte nicht geladen werden'));

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

Mindesthöhe beim Datei-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.naturalHeight < 600) {
      console.warn(`Zu klein: ${img.naturalHeight}px Höhe (mindestens 600px)`);
    } else {
      console.log('Bild akzeptiert');
    }
  } finally {
    URL.revokeObjectURL(url); // Speicher freigeben
  }
});

Zu klein: 480px Höhe (mindestens 600px)

Fehlgeschlagenes Laden erkennen

const img = new Image();
img.addEventListener('error', () => {
  console.log('naturalHeight nach Fehler:', img.naturalHeight);
});
img.src = '/gibt-es-nicht.png';

naturalHeight nach Fehler: 0

// Wichtig · Fallstricke

Der Wert ist 0, solange das Bild nicht geladen ist. Wer die Eigenschaft direkt nach dem Setzen von src ausliest, bekommt fast immer 0. Deshalb auf load oder decode() warten. Aus dem Cache geladene Bilder können schon vor dem Registrieren des Listeners fertig sein. Dann hilft die Prüfung mit img.complete.
Die Bilddichte wird herausgerechnet. Bei srcset mit 2x- oder w-Angaben entspricht naturalHeight nicht den tatsächlichen Pixeln der Datei. Die echte Pixelhöhe bekommt man z. B. über createImageBitmap(), das die Bilddaten unabhängig von der Dichte-Angabe dekodiert.
SVG-Bilder: Ohne feste Angabe von width/height im Wurzelelement (nur viewBox) hat ein SVG unter Umständen keine intrinsische Höhe. Je nach Browser ist naturalHeight dann 0 oder ein Standardwert wie 150.
EXIF-Ausrichtung: Moderne Browser werten wegen image-orientation: from-image (Standardwert) die EXIF-Ausrichtung aus. Bei hochkant aufgenommenen Handyfotos können Breite und Höhe deshalb gegenüber den Rohdaten der Datei vertauscht sein.
Kompatibilität: Wird von allen modernen Browsern unterstützt, im Internet Explorer ab Version 9. Die Eigenschaft ist schreibgeschützt; Zuweisungen werden stillschweigend ignoriert (im Strict Mode ebenfalls ohne Fehler, weil es einen Getter ohne Setter gibt, der auf dem Prototyp liegt, wird dort ein TypeError geworfen).

Siehe auch

HTMLImageElement.naturalWidth HTMLImageElement.height HTMLImageElement.complete HTMLImageElement.decode() HTMLImageElement.currentSrc