HTMLImageElement

Konstruktor

Image()

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

Instanzeigenschaften

Erbt Eigenschaften von seinem übergeordneten Element, HTMLElement.

HTMLImageElement.alt

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

HTMLImageElement.attributionSrc Sicherer Kontext

Ruft das attributionsrc Attribut eines <img> Elements programmatisch ab und setzt es, wobei der Wert dieses Attributs widergespiegelt wird. attributionsrc gibt an, dass Sie möchten, dass der Browser einen Attribution-Reporting-Eligible Header zusammen mit der Bildanfrage sendet. Serverseitig 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 fertig geladen hat, unabhängig davon, ob es erfolgreich war 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

Eine Zeichenfolge, die die CORS-Einstellung für dieses Bildelement spezifiziert. Siehe CORS Einstellungsattribute für weitere Details. Dies kann null sein, wenn CORS nicht verwendet wird.

HTMLImageElement.currentSrc Schreibgeschützt

Gibt eine Zeichenfolge zurück, die die URL darstellt, von der das derzeit angezeigte Bild geladen wurde. Dies kann sich ändern, wenn das Bild aufgrund sich ändernder Bedingungen, die durch Media Queries beeinflusst werden, angepasst wird.

HTMLImageElement.decoding

Eine optionale Zeichenfolge, die dem Browser einen Hinweis darauf gibt, wie er das Bild decodieren soll. Wenn dieser Wert angegeben wird, muss er eine der erlaubten Werte sein: sync für synchrones Decodieren, async für asynchrones Decodieren oder auto für keine Präferenz (was der Standard ist). Lesen Sie die decoding Seite für Details zu den Implikationen dieser Werte.

HTMLImageElement.fetchPriority

Eine optionale Zeichenfolge, die 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 erlaubten Werte sein: high für hohe Priorität, low für niedrige Priorität oder auto für keine Präferenz (was der Standard ist).

HTMLImageElement.height

Ein Integerwert, 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 server-seitigen Imagemap ist. Dies unterscheidet sich von einer client-seitigen Imagemap, die mit einem <img> Element und einem entsprechenden <map> erzeugt wird, welches <area> Elemente enthält, die die klickbaren Bereiche im Bild angeben. Das Bild muss innerhalb eines <a> Elements enthalten sein; lesen Sie die ismap Seite für Details.

HTMLImageElement.loading

Eine Zeichenfolge, die angibt, ob der Browser das Bild sofort (eager) oder erst bei Bedarf (lazy) laden soll.

HTMLImageElement.naturalHeight Schreibgeschützt

Gibt einen Integerwert zurück, der die intrinsische Höhe des Bildes in CSS-Pixeln darstellt, wenn verfügbar; andernfalls zeigt er 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 Integerwert, der die intrinsische Breite des Bildes in CSS-Pixeln darstellt, wenn verfügbar; 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

Eine Zeichenfolge, die das HTML-Attribut referrerpolicy widerspiegelt und dem Benutzeragenten mitteilt, wie entschieden werden soll, welcher Referrer zum Abrufen des Bildes verwendet werden soll. Lesen Sie diesen Artikel für Details zu den möglichen Werten dieser Zeichenfolge.

HTMLImageElement.sizes

Eine Zeichenfolge, die das HTML-Attribut sizes widerspiegelt. Diese Zeichenfolge gibt eine Liste aus kommagetrennten Bedingungsgröß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 sizes Seite für Details zum Format dieser Zeichenfolge.

HTMLImageElement.src

Eine Zeichenfolge, die das HTML-Attribut src 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

Eine Zeichenfolge, die das HTML-Attribut srcset widerspiegelt. Dies spezifiziert eine Liste von Kandidatenbildern, getrennt durch Kommata (',', U+002C KOMMA). Jedes Kandidatenbild ist eine URL, gefolgt von einem Leerzeichen, gefolgt von einer speziell formatierten Zeichenfolge, die die Größe des Bildes angibt. Die Größe kann entweder durch die Breite oder einen Größenfaktor angegeben werden. Lesen Sie die srcset Seite für Einzelheiten zum Format der Größenzeichensequenz.

HTMLImageElement.useMap

Eine Zeichenfolge, die das HTML-Attribut usemap widerspiegelt, das die seitenlokale URL des <map> Elements enthält, das die zu verwendende Imagemap beschreibt. Die seitenlokale URL ist ein Pfund (Hash) Symbol (#), 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 Integerwert, der das HTML-Attribut width widerspiegelt und die gerenderte Breite des Bildes in CSS-Pixeln angibt.

HTMLImageElement.x Schreibgeschützt

Ein Integerwert, der den horizontalen Versatz der linken Randkante des CSS-Layout-Box des Bildes relativ zum Ursprung des <html> Elements enthaltenden Blocks angibt.

HTMLImageElement.y Schreibgeschützt

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

Veraltete Eigenschaften

HTMLImageElement.align

Eine Zeichenfolge, die 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 festzulegen.

HTMLImageElement.border

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

HTMLImageElement.hspace

Ein Integerwert, der die Menge an Platz (in Pixeln) angibt, die links und rechts des Bildes frei gelassen werden soll.

HTMLImageElement.longDesc

Eine Zeichenfolge, die 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. Modernes HTML sollte stattdessen ein <img> innerhalb eines <a> Elements platzieren, das den Hyperlink definiert.

HTMLImageElement.name

Eine Zeichenfolge, die den Namen des Elements darstellt.

HTMLImageElement.vspace

Ein Integerwert, der die Menge an leerem Raum, in Pixeln, angibt, die oberhalb und unterhalb des Bildes freigelassen werden soll.

Instanzmethoden

Erbt Methoden von seinem übergeordneten Element, HTMLElement.

HTMLImageElement.decode()

Gibt ein Promise zurück, das aufgelöst wird, wenn das Bild decodiert 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 decodieren, wie es der Fall wäre, wenn ein undecodiertes Bild dem DOM hinzugefügt wird.

Fehler

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

• Das src Attribut ist leer oder null.
• Die angegebene src URL ist dieselbe wie die URL der Seite, auf der sich der Benutzer derzeit befindet.
• Das angegebene Bild ist in irgendeiner Weise beschädigt, die es verhindert, dass es geladen wird.
• Die Metadaten des angegebenen Bildes sind so beschädigt, dass seine Dimensionen nicht abgerufen werden können, und es wurden keine Dimensionen in den Attributen des <img> Elements angegeben.
• Das angegebene Bild ist in einem vom Benutzeragenten nicht unterstützten Format.

Beispiele

Ein Bildelement erstellen und einfügen

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 ermitteln

Das folgende Beispiel zeigt die Verwendung der height und width Eigenschaften zusammen mit Bildern unterschiedlicher Größen:

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