DasHTMLImageElement-Interface repräsentiert ein HTML-<img>-Element und bietet die Eigenschaften und Methoden, die zur Manipulation von Bildelementen verwendet werden.

Constructor

Image()

DerImage()-Konstruktor erstellt und gibt ein neuesHTMLImageElement-Objekt zurück, das ein HTML-<img>-Element repräsentiert, das nicht an einen DOM-Baum angehängt ist. Er nimmt optionale Breiten- und Höhenparameter entgegen. Wenn er ohne Parameter aufgerufen wird, entsprichtnew Image() dem Aufruf vondocument.createElement('img').

Instanz-Eigenschaften

_{*}Erbt Eigenschaften von seinem Elternteil,HTMLElement._*

HTMLImageElement.alt

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

HTMLImageElement.attributionSrcSicherer KontextExperimentell

Erhält und setzt dasattributionsrc-Attribut an einem<img>-Element programmatisch und spiegelt den Wert dieses Attributs wider.attributionsrc gibt an, dass der Browser einenAttribution-Reporting-Eligible-Header zusammen mit der Bildanfrage senden soll. Serverseitig wird dies verwendet, um das Senden einesAttribution-Reporting-Register-Source- oderAttribution-Reporting-Register-Trigger-Headers in der Antwort auszulösen, um eine bildbasierteAttributionsquelle bzw. einenAttributionstrigger zu registrieren.

HTMLImageElement.completeSchreibgeschützt

Gibt einen booleschen Wert zurück, dertrue ist, wenn der Browser das Bild erfolgreich oder nicht erfolgreich geladen hat. Das bedeutet, dass dieser Wert auchtrue ist, wenn das Bild keinensrc-Wert hat, der ein zu ladendes Bild angibt.

HTMLImageElement.crossOrigin

Ein String, der die CORS-Einstellung für dieses Bildelement angibt. Weitere Informationen finden Sie unterCORS-Attributen. Dies kannnull sein, wenn CORS nicht verwendet wird.

HTMLImageElement.currentSrcSchreibgeschützt

Gibt einen String zurück, der die URL angibt, von der das derzeit angezeigte Bild geladen wurde. Dies kann sich ändern, da das Bild aufgrund sich ändernder Bedingungen angepasst wird, wie sie von gegebenenMedia-Queries vorgegeben werden.

HTMLImageElement.decoding

Ein optionaler String, der dem Browser einen Hinweis darauf gibt, wie er das Bild dekodieren soll. 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, oderauto, um keine Präferenz anzugeben (was der Standard ist). Lesen Sie diedecoding-Seite für Details zu den Implikationen der Werte dieser Eigenschaft.

HTMLImageElement.fetchPriority

Ein optionaler String, der dem Browser einen Hinweis darauf gibt, wie er die Priorität beim Laden des Bildes im Vergleich zu anderen Bildern setzen soll. Wenn dieser Wert angegeben wird, muss er einer der möglichen zulässigen Werte sein:high, um mit hoher Priorität zu laden,low, um mit niedriger Priorität zu laden, oderauto für keine spezifische Präferenz (was der Standard ist).

HTMLImageElement.height

Ein Ganzzahlwert, der dasheight-HTML-Attribut widerspiegelt und die gerenderte Höhe des Bildes in CSS-Pixeln angibt.

HTMLImageElement.isMap

Ein boolescher Wert, der dasismap-HTML-Attribut 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>-Element, das<area>-Elemente enthält, die die klickbaren Bereiche im Bild angeben, spezifiziert wird. Das Bildmuss innerhalb eines<a>-Elements enthalten sein; sehen Sie sich dieismap-Seite für nähere Informationen an.

HTMLImageElement.loading

Ein String, der dem Browser einen Hinweis gibt, wie das Dokument optimiert geladen werden kann, indem bestimmt wird, ob das Bild sofort (eager) oder bei Bedarf (lazy) geladen werden soll.

HTMLImageElement.naturalHeightSchreibgeschützt

Gibt einen ganzzahligen Wert zurück, der die intrinsische Höhe des Bildes in CSS-Pixeln darstellt, falls diese verfügbar ist; andernfalls zeigt er0. Dies ist die Höhe, die das Bild hätte, wenn es in seiner natürlichen vollen Größe gerendert würde.

HTMLImageElement.naturalWidthSchreibgeschützt

Ein ganzzahliger Wert, der die intrinsische Breite des Bildes in CSS-Pixeln darstellt, falls diese verfügbar ist; andernfalls zeigt er0. Dies ist die Breite, die das Bild hätte, wenn es in seiner natürlichen vollen Größe gerendert würde.

HTMLImageElement.referrerPolicy

Ein String, der dasreferrerpolicy-HTML-Attribut widerspiegelt und denUser-Agent darüber informiert, wie er entscheiden soll, welchen Referrer verwenden werden soll, um das Bild abzurufen. Lesen Sie diesen Artikel für Details zu den möglichen Werten dieses Strings.

HTMLImageElement.sizes

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

HTMLImageElement.src

Ein String, der dassrc-HTML-Attribut widerspiegelt und 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 imsrc-Attribut ändern.

HTMLImageElement.srcset

Ein String, der dassrcset-HTML-Attribut widerspiegelt. Dies gibt eine Liste von Kandidatenbildern an, die durch Kommas (',', U+002C KOMMA) 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 in der Breite oder als Größenmultiplikator angegeben sein. Lesen Sie diesrcset-Seite für genaue Informationen zum Format des Größen-Teils.

HTMLImageElement.useMap

Ein String, der dasusemap-HTML-Attribut widerspiegelt und die seitenlokale URL des<map>-Elements enthält, das die zu verwendende Bildkarte beschreibt. Die seitenlokale URL ist ein Raute-Zeichen (#) gefolgt vomname des<map>-Elements, z. B.#my-map-element. Das<map> wiederum enthält<area>-Elemente, die die klickbaren Bereiche im Bild angeben.

HTMLImageElement.width

Ein Ganzzahlwert, der daswidth-HTML-Attribut widerspiegelt und die gerenderte Breite des Bildes in CSS-Pixeln angibt.

HTMLImageElement.xSchreibgeschützt

Ein Ganzzahlwert, der den horizontalen Versatz des linken Randes der CSS-Layoutbox des Bildes relativ zum Ursprung des<html>-Elements enthaltenden Blocks angibt.

HTMLImageElement.ySchreibgeschützt

Der ganzzahlige vertikale Versatz des oberen Randes der CSS-Layoutbox des Bildes relativ zum Ursprung des<html>-Elements enthaltenden Blocks.

Veraltete Eigenschaften

HTMLImageElement.alignVeraltet

Ein String, der die Ausrichtung des Bildes in Bezug auf den umgebenden Kontext angibt. Die möglichen Werte sind"left","right","justify" und"center". Dies ist veraltet; Sie sollten stattdessen CSS (wie z.B.text-align, das trotz seines Namens auch mit Bildern funktioniert) verwenden, um die Ausrichtung festzulegen.

HTMLImageElement.borderVeraltet

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

HTMLImageElement.hspaceVeraltet

Ein ganzzahliger Wert, der die Menge des Raums (in Pixeln) angibt, der auf der linken und rechten Seite des Bildes leer bleiben soll.

HTMLImageElement.longDescVeraltet

Ein String, der die URL angibt, unter der eine lange Beschreibung der Bildinhalte zu finden ist. Dies wird verwendet, um das Bild automatisch in einen Hyperlink zu verwandeln. Moderne HTML sollte stattdessen ein<img> in einem<a>-Element, das den Hyperlink definiert, platzieren.

HTMLImageElement.nameVeraltet

Ein String, der den Namen des Elements repräsentiert.

HTMLImageElement.vspaceVeraltet

Ein ganzzahliger Wert, der die Menge des leeren Raums in Pixeln, die über und unter dem Bild gelassen werden soll, angibt.

Instanz-Methoden

_{*}Erbt Methoden von seinem Elternteil,HTMLElement._*

HTMLImageElement.decode()

Gibt einPromise zurück, das aufgelöst wird, wenn das Bild dekodiert wurde und es sicher ist, das Bild in den DOM einzufügen. Dies verhindert, dass das Rendering des nächsten Frames pausieren muss, um das Bild zu dekodieren, was passieren würde, wenn ein nicht dekodiertes Bild in den DOM hinzugefügt würde.

Fehler

Wenn ein Fehler auftritt, während versucht wird, das Bild zu laden oder darzustellen, und einonerror-Ereignis-Handler konfiguriert wurde, um daserror-Ereignis zu behandeln, wird dieser Ereignis-Handler aufgerufen. Dies kann in einer Reihe von Situationen geschehen, einschließlich:

• Dassrc-Attribut ist leer odernull.
• Die angegebenesrc-URL ist dieselbe wie die URL der Seite, auf der sich der Benutzer aktuell befindet.
• Das angegebene Bild ist auf eine Weise beschädigt, die verhindert, dass es geladen wird.
• Die Metadaten des angegebenen Bildes sind so beschädigt, dass es unmöglich ist, seine Dimensionen zu ermitteln, und keine Dimensionen wurden in den<img>-Element-Attributen angegeben.
• Das angegebene Bild ist in einem vomUser-Agent nicht unterstützten Format.

Beispiele

Erstellen und Einfügen eines Bildelements

const img1 = new Image(); // Image constructorimg1.src = "image1.png";img1.alt = "alt";document.body.appendChild(img1);const img2 = document.createElement("img"); // Use DOM HTMLImageElementimg2.src = "image2.jpg";img2.alt = "alt text";document.body.appendChild(img2);// using first image in the documentalert(document.images[0].src);

Breite und Höhe abrufen

Das folgende Beispiel zeigt die Verwendung der Eigenschaftenheight undwidth zusammen mit Bildern unterschiedlicher Dimensionen:

<p>  Image 1: no height, width, or style  <img src="https://www.mozilla.org/images/mozilla-banner.gif" /></p><p>  Image 2: height="50", width="500", but no style  <img       src="https://www.mozilla.org/images/mozilla-banner.gif"    height="50"    width="500" /></p><p>  Image 3: no height, width, but  <img       src="https://www.mozilla.org/images/mozilla-banner.gif"    /></p><div></div>

const arrImages = [  document.getElementById("image1"),  document.getElementById("image2"),  document.getElementById("image3"),];const objOutput = document.getElementById("output");let strHtml = "<ul>";for (let i = 0; i < arrImages.length; i++) {  const img = arrImages[i];  strHtml += `<li>image${i + 1}: height=${img.height}, width=${img.width}, style.height=${img.style.height}, style.width=${img.style.width}</li>`;}strHtml += "</ul>";objOutput.innerHTML = strHtml;

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Das HTML-Element, das dieses Interface implementiert:<img>