HTMLImageElement

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Die HTMLImageElement-Schnittstelle repräsentiert ein HTML <img>-Element und bietet die Eigenschaften und Methoden zur Manipulation von Bildelementen.

EventTarget Node Element HTMLElement HTMLImageElement

Konstruktor

Image()

Der Image()-Konstruktor erstellt und gibt ein neues HTMLImageElement-Objekt zurück, welches ein HTML <img>-Element darstellt, das nicht an einen beliebigen DOM-Baum angehängt ist. Er akzeptiert optionale Breiten- und Höhenparameter. Wird er ohne Parameter aufgerufen, ist new Image() gleichbedeutend mit dem Aufruf von document.createElement('img').

Instanz-Eigenschaften

Erbt Eigenschaften von seiner Elternklasse, HTMLElement.

HTMLImageElement.alt

Ein String, der das HTML-Attribut alt widerspiegelt und somit den alternativen Fallback-Inhalt angibt, der angezeigt werden soll, wenn das Bild nicht geladen werden konnte.

HTMLImageElement.attributionSrc Sicherer Kontext

Ruft das Attribut attributionsrc eines <img>-Elements ab oder setzt es programmatisch und spiegelt den Wert dieses Attributs wider. attributionsrc legt fest, dass der Browser einen Attribution-Reporting-Eligible-Header zusammen mit der Bildanforderung senden soll. Serverseitig wird dies genutzt, um das Senden eines Attribution-Reporting-Register-Source- oder Attribution-Reporting-Register-Trigger-Headers in der Antwort auszulösen, um eine auf Bildern basierende Attributionsquelle oder einen Attributionstrigger zu registrieren.

HTMLImageElement.complete Schreibgeschützt

Gibt einen booleschen Wert zurück, der true ist, wenn der Browser das Bild erfolgreich oder nicht erfolgreich geladen hat. Dies bedeutet, dass dieser Wert auch true ist, wenn das Bild keinen src-Wert hat, der ein zu ladendes Bild angibt.

HTMLImageElement.crossOrigin

Ein String, der die CORS-Einstellung für dieses Bildelement angibt. Siehe CORS-Einstellungsattribute für weitere Details. Dies kann null sein, wenn CORS nicht verwendet wird.

HTMLImageElement.currentSrc Schreibgeschützt

Gibt einen String zurück, der die URL repräsentiert, von der das aktuell angezeigte Bild geladen wurde. Dies kann sich ändern, wenn das Bild aufgrund wechselnder Bedingungen, wie durch vorhandene Media Queries, angepasst wird.

HTMLImageElement.decoding

Ein optionaler String, der dem Browser einen Hinweis gibt, wie das Bild dekodiert werden sollte. Wenn dieser Wert angegeben wird, muss er einer der möglichen zulässigen Werte sein: sync, um das Bild synchron zu dekodieren, async, um es asynchron zu dekodieren, oder auto, um keine Präferenz anzugeben (was der Standard ist). Lesen Sie die Seite decoding für Details zu den Auswirkungen der Werte dieser Eigenschaft.

HTMLImageElement.fetchPriority

Ein optionaler String, der dem Browser einen Hinweis gibt, wie er das Laden des Bildes im Verhältnis zu anderen Bildern priorisieren soll. Wenn dieser Wert angegeben wird, muss er einer der möglichen erlaubten Werte sein: high für hohe Priorität beim Laden, low für niedrige Priorität oder auto, um keine Präferenz anzugeben (was der Standard ist).

HTMLImageElement.height

Ein ganzzahliger Wert, der das HTML-Attribut height widerspiegelt, was die gerenderte Höhe des Bildes in CSS-Pixeln angibt.

HTMLImageElement.isMap

Ein boolescher Wert, der das HTML-Attribut ismap widerspiegelt und angibt, dass das Bild Teil einer serverseitigen Bildkarte ist. Dies unterscheidet sich von einer clientseitigen Bildkarte, die mit einem <img>-Element und einem entsprechenden <map> definiert wird, das <area>-Elemente enthält, die die klickbaren Bereiche im Bild anzeigen. Das Bild muss in einem <a>-Element enthalten sein; siehe die ismap-Seite für Details.

HTMLImageElement.loading

Ein String, der dem Browser einen Hinweis gibt, der verwendet wird, um das Laden des Dokuments zu optimieren, indem bestimmt wird, ob das Bild sofort (eager) oder bei Bedarf (lazy) geladen werden soll.

HTMLImageElement.naturalHeight Schreibgeschützt

Gibt einen ganzzahligen Wert zurück, der die intrinsische Höhe des Bildes in CSS-Pixeln angibt, wenn verfügbar; andernfalls wird 0 angezeigt. Dies ist die Höhe, die das Bild hätte, wenn es in seiner natürlichen vollen Größe gerendert wird.

HTMLImageElement.naturalWidth Schreibgeschützt

Ein ganzzahliger Wert, der die intrinsische Breite des Bildes in CSS-Pixeln angibt, wenn verfügbar; andernfalls wird 0 angezeigt. Dies ist die Breite, die das Bild hätte, wenn es in seiner natürlichen vollen Größe gerendert wird.

HTMLImageElement.referrerPolicy

Ein String, der das HTML-Attribut referrerpolicy widerspiegelt und dem User Agent mitteilt, wie entschieden werden soll, welchen Referrer zur Anforderung des Bildes verwendet werden soll. Lesen Sie diesen Artikel für Details zu den möglichen Werten dieses Strings.

HTMLImageElement.sizes

Ein String, der das HTML-Attribut sizes widerspiegelt. Dieser String gibt eine Liste von kommaseparierten bedingten Größen für das Bild an; das heißt, für eine gegebene Viewport-Größe soll eine bestimmte Bildgröße verwendet werden. Lesen Sie die Dokumentation auf der Seite sizes für Details zum Format dieses Strings.

HTMLImageElement.src

Ein String, der das HTML-Attribut src widerspiegelt, das die vollständige URL des Bildes einschließlich der Basis-URI enthält. Sie können ein anderes Bild in das Element laden, indem Sie die URL im src-Attribut ändern.

HTMLImageElement.srcset

Ein String, der das HTML-Attribut srcset widerspiegelt. Dies gibt eine Liste von Kandidatenbildern an, die durch Kommas (',', U+002C COMMA) getrennt sind. Jedes Kandidatenbild ist eine URL, gefolgt von einem Leerzeichen, gefolgt von einem speziell formatierten String, der die Größe des Bildes angibt. Die Größe kann entweder durch die Breite oder einen Größenfaktor angegeben werden. Lesen Sie die Seite srcset für spezifische Informationen zum Format des Größen-Substrings.

HTMLImageElement.useMap

Ein String, der das HTML-Attribut usemap widerspiegelt und die seiteninterne URL des <map>-Elements enthält, das die zu verwendende Bildkarte beschreibt. Die seiteninterne URL ist ein Rautezeichen (#) gefolgt von der ID des <map>-Elements, wie z.B. #my-map-element. Das <map> enthält wiederum <area>-Elemente, die die klickbaren Bereiche im Bild anzeigen.

HTMLImageElement.width

Ein ganzzahliger Wert, der das HTML-Attribut width widerspiegelt, das die gerenderte Breite des Bildes in CSS-Pixeln angibt.

HTMLImageElement.x Schreibgeschützt

Ein ganzzahliger Wert, der den horizontalen Versatz der linken Randkante des CSS-Layoutkastens des Bildes relativ zum Ursprung des enthaltenen Blocks des <html>-Elements angibt.

HTMLImageElement.y Schreibgeschützt

Der ganzzahlige vertikale Versatz der oberen Randkante des CSS-Layoutkastens des Bildes relativ zum Ursprung des enthaltenen Blocks des <html>-Elements.

Veraltete Eigenschaften

HTMLImageElement.align

Ein String, der die Ausrichtung des Bildes im Verhältnis zum umgebenden Kontext angibt. Die möglichen Werte sind "left", "right", "justify" und "center". Dies ist veraltet; Sie sollten stattdessen CSS (wie text-align, das trotz seines Namens mit Bildern funktioniert) verwenden, um die Ausrichtung zu spezifizieren.

HTMLImageElement.border

Ein String, der die Breite des Rahmens um das Bild herum definiert. Dies ist veraltet; verwenden Sie stattdessen die CSS-Eigenschaft border.

HTMLImageElement.hspace

Ein ganzzahliger Wert, der die Menge an leerem Raum (in Pixeln) bestimmt, die links und rechts vom Bild frei bleiben soll.

HTMLImageElement.longDesc

Ein String, der die URL angibt, unter der eine ausführliche Beschreibung der Bildinhalte zu finden ist. Dies wird verwendet, um das Bild automatisch in einen Hyperlink zu verwandeln. Moderne HTML-Techniken sollten stattdessen ein <img> innerhalb eines <a>-Elements platzieren, das den Hyperlink definiert.

HTMLImageElement.name

Ein String, der den Namen des Elements darstellt.

HTMLImageElement.vspace

Ein ganzzahliger Wert, der die Menge an leerem Raum, in Pixeln, angibt, die über und unter dem Bild frei gelassen werden soll.

Instanz-Methoden

Erbt Methoden von seiner Elternklasse, HTMLElement.

HTMLImageElement.decode()

Gibt ein Promise zurück, das sich auflöst, wenn das Bild dekodiert ist und es sicher ist, das Bild dem DOM hinzuzufügen. Dies verhindert, dass das Rendern des nächsten Frames pausieren muss, um das Bild zu dekodieren, wie es passieren würde, wenn ein unkodiertes Bild dem DOM hinzugefügt wird.

Fehler

Wenn ein Fehler beim Versuch auftritt, das Bild zu laden oder zu rendern, und ein onerror-Ereignishandler konfiguriert ist, um das error-Ereignis zu behandeln, wird dieser Ereignishandler aufgerufen. Dies kann in einer Reihe von Situationen passieren, einschließlich:

  • Das [src](/de/docs/Web/HTML/Reference/Elements/img#src)-Attribut ist leer oder null.
  • Die angegebene src-URL ist dieselbe wie die URL der Seite, die der Benutzer gerade besucht.
  • Das angegebene Bild ist in irgendeiner Weise beschädigt, die das Laden verhindert.
  • Die angegebene Bildmetadaten sind so beschädigt, dass es unmöglich ist, seine Dimensionen abzurufen, und es wurden keine Dimensionen in den Attributen des <img>-Elements angegeben.
  • Das angegebene Bild ist in einem Format, das vom User Agent nicht unterstützt wird.

Beispiel

js
const img1 = new Image(); // Image constructor
img1.src = "image1.png";
img1.alt = "alt";
document.body.appendChild(img1);

const img2 = document.createElement("img"); // Use DOM HTMLImageElement
img2.src = "image2.jpg";
img2.alt = "alt text";
document.body.appendChild(img2);

// using first image in the document
alert(document.images[0].src);

Spezifikationen

Specification
HTML
# htmlimageelement

Browser-Kompatibilität

Siehe auch

  • Das HTML-Element, das diese Schnittstelle implementiert: <img>