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.

Die HTMLImageElement Schnittstelle repräsentiert ein HTML <img> Element und bietet die Eigenschaften und Methoden, die zur Manipulation von Bild-Elementen verwendet werden.

EventTarget Node Element HTMLElement HTMLImageElement

Konstruktor

Image()

Der Image()-Konstruktor erstellt und gibt ein neues HTMLImageElement-Objekt zurück, das ein HTML <img> Element repräsentiert, welches an keinen DOM-Baum angehängt ist. Es akzeptiert optionale Breiten- und Höhenparameter. Wenn es ohne Parameter aufgerufen wird, ist new Image() äquivalent zu einem 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 wird, wenn das Bild nicht geladen wurde.

HTMLImageElement.attributionSrc Sicherer Kontext

Der Wert des attributionsrc Attributs auf einem <img> Element wird programmatisch abgerufen und gesetzt, was den Wert dieses Attributs widerspiegelt. attributionsrc gibt an, dass der Browser einen Attribution-Reporting-Eligible Header zusammen mit dem Bildantrag 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 bzw. einen Attributionstrigger zu registrieren.

HTMLImageElement.complete Schreibgeschützt

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

HTMLImageElement.crossOrigin

Ein String, der die CORS-Einstellungen für dieses Bildelement angibt. Siehe CORS-Einstellungen-Attribute 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, da das Bild aufgrund sich ändernder Bedingungen angepasst wird, wie es von vorhandenen Media Queries vorgeschrieben wird.

HTMLImageElement.decoding

Ein optionaler String, der dem Browser einen Hinweis gibt, wie das Bild dekodiert werden soll. Wenn dieser Wert festgelegt ist, muss er einer der möglichen erlaubten Werte sein: sync für eine synchrone Dekodierung, async für eine asynchrone Dekodierung 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 gibt, wie er das Laden des Bildes im Verhältnis zu anderen Bildern priorisieren soll. Wenn dieser Wert angegeben ist, muss er einer der erlaubten Werte sein: high für hohe Priorität, low für niedrige Priorität oder auto, um keine Präferenz anzugeben (der Standard).

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 Image-Map ist. Dies unterscheidet sich von einer clientseitigen Image-Map, die mit einem <img>-Element und einem entsprechenden <map> spezifiziert wird, welches <area> Elemente enthält, die die klickbaren Bereiche im Bild kennzeichnen. Das Bild muss in ein <a> Element eingebettet werden; siehe die ismap Seite für Details.

HTMLImageElement.loading

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

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 zeigt er 0. 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 angibt, wenn verfügbar; andernfalls zeigt er 0. 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 referrerpolicy HTML-Attribut widerspiegelt, das dem User-Agent mitteilt, wie er den Referrer auswählen 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 spezifiziert eine Liste von durch Komma getrennten bedingten Größen für das Bild. Das heißt, für eine gegebene Ansichtsgröß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 src HTML-Attribut widerspiegelt, das die vollständige URL des Bildes inklusive 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 spezifiziert eine Liste von Kandidatenbildern, getrennt durch Kommas (',', U+002C COMMA). Jedes Kandidatenbild ist eine URL, gefolgt von einem Leerzeichen und 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 Seite srcset für Details zum Format des Größen-Strings.

HTMLImageElement.useMap

Ein String, der das usemap HTML-Attribut widerspiegelt und die seitenlokale URL des <map>-Elements enthält, das die zu verwendende Image-Map beschreibt. Die seitenlokale URL ist ein Nummernzeichen (#) gefolgt von der ID 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 Integer, der den horizontalen Versatz der linken Rahmenkante des Bildes relativ zum Ursprung des CSS-Layout-Blocks des <html> Elements angibt.

HTMLImageElement.y Schreibgeschützt

Der Integer, der den vertikalen Versatz der oberen Rahmenkante des Bildes relativ zum Ursprung des CSS-Layout-Blocks des <html> Elements angibt.

Veraltete Eigenschaften

HTMLImageElement.align

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

HTMLImageElement.border

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

HTMLImageElement.hspace

Ein ganzzahliger Wert, der angibt, wie viel Platz (in Pixeln) auf der linken und rechten Seite des Bildes freizuhalten ist.

HTMLImageElement.longDesc

Ein String, der die URL angibt, unter der eine lange Beschreibung des Bildinhalts gefunden werden kann. Dies wird verwendet, um das Bild automatisch in einen Hyperlink zu verwandeln. Modernes HTML sollte stattdessen ein <img> in ein <a> Element einfügen, das den Hyperlink definiert.

HTMLImageElement.name

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

HTMLImageElement.vspace

Ein ganzzahliger Wert, der angibt, wie viel Platz, in Pixeln, ober- und unterhalb des Bildes freizuhalten ist.

Instanzmethoden

Übernimmt Methoden von seinem Elternteil, HTMLElement.

HTMLImageElement.decode()

Gibt ein Promise zurück, das sich auflöst, wenn das Bild dekodiert ist und es sicher ist, das Bild an den DOM anzufügen. Dies verhindert, dass das Rendering des nächsten Frames pausieren muss, um das Bild zu dekodieren, wie es der Fall wäre, 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 Event-Handler eingerichtet ist, um das error Event zu behandeln, wird dieser Event-Handler aufgerufen. Dies kann in mehreren Situationen passieren, einschließlich:

  • Das src Attribut ist leer oder null.
  • Die angegebene src URL ist dieselbe wie die URL der Seite, die der Benutzer derzeit besucht.
  • Das angegebene Bild ist in irgendeiner Weise beschädigt, die es daran hindert, geladen zu werden.
  • Die Metadaten des angegebenen Bildes sind so beschädigt, dass es unmöglich ist, seine Dimensionen abzurufen und keine Dimensionen im <img>-Element' 's Attributen angegeben wurden.
  • 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 Standard
# htmlimageelement

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch

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