HTMLImageElement

Konstruktor

Image()

Der Image()-Konstruktor erstellt und liefert ein neues HTMLImageElement-Objekt, das ein HTML-<img>-Element repräsentiert, das nicht an einen DOM-Baum angefügt ist. Er akzeptiert optionale Breiten- und Höhenparameter. Wird er ohne Parameter aufgerufen, ist new Image() gleichbedeutend mit dem Aufruf von document.createElement('img').

Instanzeigenschaften

Übernimmt Eigenschaften von seinem Elternteil, HTMLElement.

HTMLImageElement.alt

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

HTMLImageElement.attributionSrc Sicherer Kontext Veraltet

Ruft das attributionsrc-Attribut für ein <img>-Element ab und setzt es programmatisch, wobei der Wert dieses Attributs widergespiegelt wird. attributionsrc gibt an, dass der Browser einen Attribution-Reporting-Eligible-Header mit der Bildanforderung senden soll. Auf der Serverseite wird dies verwendet, um das Senden eines Attribution-Reporting-Register-Source- oder Attribution-Reporting-Register-Trigger-Headers in der Antwort auszulösen, um eine bildbasierte 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) vollständig geladen hat. Das 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 sich ändernder Bedingungen angepasst wird, wie sie durch vorhandene Media Queries festgelegt sind.

HTMLImageElement.decoding

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

HTMLImageElement.fetchPriority

Ein optionaler String, der dem Browser einen Hinweis darauf gibt, wie er das Abrufen des Bildes im Vergleich zu anderen Bildern priorisieren soll. Wenn dieser Wert bereitgestellt wird, muss er einer der möglichen zulässigen Werte sein: high, um mit hoher Priorität abzurufen, low, um mit niedriger Priorität abzurufen, oder auto, um keine Präferenz anzugeben (was der Standard ist).

HTMLImageElement.height

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

HTMLImageElement.isMap

Ein boolescher Wert, der das ismap-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> spezifiziert wird, das <area>-Elemente enthält, die die klickbaren Bereiche im Bild angeben. Das Bild muss innerhalb eines <a>-Elements enthalten sein; siehe die ismap-Seite für Details.

HTMLImageElement.loading

Ein String, der angibt, ob der Browser das Bild sofort (eager) oder bei Bedarf (lazy) laden soll.

HTMLImageElement.naturalHeight Schreibgeschützt

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

HTMLImageElement.naturalWidth Schreibgeschützt

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

HTMLImageElement.referrerPolicy

Ein String, der das referrerpolicy-HTML-Attribut widerspiegelt, das dem User-Agent mitteilt, wie er entscheiden soll, welchen Referrer er verwenden soll, um das Bild abzurufen. Lesen Sie diesen Artikel für Details zu den möglichen Werten dieses Strings.

HTMLImageElement.sizes

Ein String, der das sizes-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 bestimmte Größe des Viewports soll eine bestimmte Bildgröße verwendet werden. Lesen Sie die Dokumentation auf der sizes-Seite für Details zum Format dieses Strings.

HTMLImageElement.src

Ein String, der das src-HTML-Attribut widerspiegelt, welches 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 srcset-HTML-Attribut 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 als Breite oder als Vielfaches der Größe angegeben werden. Lesen Sie die srcset-Seite für genaue Angaben zum Format des Größen-Substrings.

HTMLImageElement.useMap

Ein String, der das usemap-HTML-Attribut widerspiegelt, welches die seitenlokale URL des <map>-Elements enthält, das die zu verwendende Bildkarte beschreibt. Die seitenlokale URL ist ein Rautensymbol (#), gefolgt vom name des <map>-Elements, wie #my-map-element. Das <map> enthält wiederum <area>-Elemente, die die klickbaren Bereiche im Bild angeben.

HTMLImageElement.width

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

HTMLImageElement.x Schreibgeschützt

Ein ganzzahliger Wert, der den horizontalen Versatz der linken Rahmenkante des CSS-Layout-Box des Bildes relativ zum Ursprung des Container-Blocks des <html>-Elements angibt.

HTMLImageElement.y Schreibgeschützt

Der ganzzahlige vertikale Versatz der oberen Rahmenkante des CSS-Layout-Box des Bildes relativ zum Ursprung des Container-Blocks des <html>-Elements.

Veraltete Eigenschaften

HTMLImageElement.align Veraltet

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 text-align, das trotz seines Namens mit Bildern funktioniert) verwenden, um die Ausrichtung zu spezifizieren.

HTMLImageElement.border Veraltet

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

HTMLImageElement.hspace Veraltet

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

HTMLImageElement.longDesc Veraltet

Ein String, der die URL angibt, unter der eine lange Beschreibung des Bildinhalts zu finden ist. Dies wird verwendet, um das Bild automatisch in einen Hyperlink zu verwandeln. Modernes HTML sollte stattdessen ein <img> innerhalb eines <a>-Elements platzieren, das den Hyperlink definiert.

HTMLImageElement.name Veraltet

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

HTMLImageElement.vspace Veraltet

Ein ganzzahliger Wert, der die Menge an Leerraum in Pixeln angibt, die oberhalb und unterhalb des Bildes verbleiben soll.

Instanzmethoden

Übernimmt Methoden von seinem Elternteil, HTMLElement.

HTMLImageElement.decode()

Gibt ein Promise zurück, das aufgelöst wird, wenn das Bild decodiert ist und sicher an den DOM angehängt werden kann. Dies verhindert, dass das Rendern des nächsten Frames pausiert, um das Bild zu decodieren, so wie es passieren würde, wenn ein undecodiertes Bild zum DOM hinzugefügt würde.

Fehler

Wenn ein Fehler beim Laden oder Rendern des Bildes auftritt und ein onerror-Ereignishandler konfiguriert wurde, um das error-Ereignis zu behandeln, wird dieser Ereignishandler aufgerufen. Dies kann in einer Reihe von Situationen geschehen, einschließlich:

• Das src-Attribut ist leer oder null.
• Die angegebene src-URL ist identisch mit der URL der Seite, die der Benutzer gerade aufgerufen hat.
• Das angegebene Bild ist in irgendeiner Weise beschädigt, dass es nicht geladen werden kann.
• Die Metadaten des angegebenen Bildes sind so beschädigt, dass es unmöglich ist, seine Dimensionen abzurufen, und keine Dimensionen wurden in den Attributen des <img>-Elements angegeben.
• Das angegebene Bild ist in einem Format, das vom User-Agent nicht unterstützt wird.

Beispiele

Erstellen und Einfügen eines Bildelements

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);

Breite und Höhe erhalten

Das folgende Beispiel zeigt die Verwendung der height- und width-Eigenschaften zusammen mit Bildern unterschiedlicher Dimensionen:

<p>
  Image 1: no height, width, or style
  <img id="image1" src="https://www.mozilla.org/images/mozilla-banner.gif" />
</p>

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

<p>
  Image 3: no height, width, but style="height: 50px; width: 500px;"
  <img
    id="image3"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
    style="height: 50px; width: 500px;" />
</p>

<div id="output"></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>