HTMLImageElement

Konstruktor

Image()

Der Image() Konstruktor erstellt und gibt ein neues HTMLImageElement Objekt zurück, das ein HTML <img>-Element darstellt, das nicht mit einem DOM-Baum verbunden ist. Es akzeptiert optionale Breiten- und Höhenparameter. Wenn es ohne Parameter aufgerufen wird, entspricht new Image() dem Aufruf von document.createElement('img').

Instanzeigenschaften

Erbt Eigenschaften von seinem Elternteil, 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 wurde.

HTMLImageElement.attributionSrc Sicherer Kontext Veraltet

Ruft das attributionsrc Attribut auf einem <img>-Element ab und setzt es programmatisch, was den Wert dieses Attributs widerspiegelt. attributionsrc gibt an, dass Sie möchten, dass der Browser einen Attribution-Reporting-Eligible Header zusammen mit der Bildanforderung sendet. Auf der Serverseite wird dies verwendet, um das Senden von Attribution-Reporting-Register-Source oder Attribution-Reporting-Register-Trigger Header im Antwortschreiben auszulösen, um eine bildbasierte Attributionsquelle bzw. einen Attributionstrigger zu registrieren.

HTMLImageElement.complete Schreibgeschützt

Gibt einen booleschen Wert zurück, der true ist, wenn der Browser das Bild abgeschlossen hat, ob erfolgreich oder nicht. 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 spezifiziert. Weitere Einzelheiten finden Sie unter CORS-Einstellungsattribute. 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 es durch vorhandene Media Queries festgelegt ist.

HTMLImageElement.decoding

Ein optionaler String, der dem Browser einen Hinweis darauf gibt, wie das Bild dekodiert werden soll. Wenn dieser Wert angegeben wird, muss er einer der möglichen erlaubten 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 darauf gibt, wie er das Abrufen des Bildes im Vergleich zu anderen Bildern priorisieren soll. Wenn dieser Wert angegeben wird, muss er einer der möglichen erlaubten 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 HTML-Attribut height widerspiegelt und 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 Image-Map ist. Dies unterscheidet sich von einer clientseitigen Image-Map, die mit einem <img>-Element und einem entsprechenden <map> erstellt wird, das <area>-Elemente enthält, die die anklickbaren Bereiche im Bild angeben. Das Bild muss in einem <a> Element enthalten sein; sehen Sie die ismap-Seite für Details.

HTMLImageElement.loading

Ein String, der dem Browser einen Hinweis darauf gibt, das Laden des Dokuments zu optimieren, indem festgelegt wird, ob das Bild sofort (eager) oder erst 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 darstellt, wenn es verfügbar ist; andernfalls zeigt es 0 an. Dies ist die Höhe, die das Bild hätte, wenn es in seiner natürlichen vollen Größe gerendert würde.

HTMLImageElement.naturalWidth Schreibgeschützt

Ein ganzzahliger Wert, der die intrinsische Breite des Bildes in CSS-Pixeln darstellt, wenn es verfügbar ist; andernfalls zeigt es 0 an. 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 das HTML-Attribut referrerpolicy widerspiegelt, das dem User-Agent mitteilt, wie er entscheiden soll, welchen Verweis verwendet 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 das HTML-Attribut sizes widerspiegelt. Dieser String gibt eine Liste von kommagetrennten bedingten Größen für das Bild an; das heißt, für eine gegebene Ansichtsfenstergröße 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 HTML-Attribut src widerspiegelt und die vollständige URL des Bildes einschließlich 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 getrennt sind (',', U+002C COMMA). 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ößenmultiplikator angegeben werden. Lesen Sie die srcset Seite für Details zum Format des Größen-Substrings.

HTMLImageElement.useMap

Ein String, der das HTML-Attribut usemap widerspiegelt und die seitenlokale URL des <map>-Elements enthält, das die zu verwendende Image-Map beschreibt. Die seitenlokale URL ist ein Hashtag-Symbol (#), gefolgt von dem name des <map>-Elements, wie z. B. #my-map-element. Das <map> enthält wiederum <area>-Elemente, die die anklickbaren Bereiche im Bild angeben.

HTMLImageElement.width

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

HTMLImageElement.x Schreibgeschützt

Ein Ganzzahlwert, der den horizontalen Versatz der linken Rahmenkante des CSS-Layout-Box des Bildes relativ zum Ursprung des <html> Elements in seinem enthaltenden Block angibt.

HTMLImageElement.y Schreibgeschützt

Der ganzzahlig vertikale Versatz der oberen Rahmenkante des CSS-Layout-Box des Bildes relativ zum Ursprung des <html> Elements in seinem enthaltenden Block.

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

HTMLImageElement.border Veraltet

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

HTMLImageElement.hspace Veraltet

Ein ganzzahliger Wert, der angibt, wie viel Platz (in Pixeln) 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 der Bildinhalte zu finden ist. Dies wird verwendet, um das Bild automatisch in einen Hyperlink zu verwandeln. Moderne 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 angibt, wie viel Platz (in Pixeln) über und unter dem Bild leer bleiben soll.

Instanzmethoden

Erbt Methoden von seinem Elternteil, HTMLElement.

HTMLImageElement.decode()

Gibt ein Promise zurück, das aufgelöst wird, 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 geschehen würde, wenn ein nicht dekodiertes Bild dem DOM hinzugefügt würde.

Fehler

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

• Das src Attribut ist leer oder null.
• Die angegebene src URL ist die gleiche wie die URL der Seite, auf der sich der Benutzer gerade befindet.
• Das angegebene Bild ist in irgendeiner Weise beschädigt, was verhindert, dass es geladen wird.
• 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 nicht von dem User-Agent 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);

Ermitteln von Breite und Höhe

Das folgende Beispiel zeigt die Verwendung der height- und width-Eigenschaften 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 diese Schnittstelle implementiert: <img>