HTMLImageElement

HTMLImageElement 介面提供了特殊的屬性及方法以用來操作 <img> 元素的畫面佈局與外觀呈現。

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/zh-TW/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25  121,20  121,30  111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/zh-TW/docs/Web/API/Node" target="_top"><rect x="151" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="188.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Node</text></a><polyline points="226,25  236,20  236,30  226,25" stroke="#D4DDE4" fill="none"/><line x1="236" y1="25" x2="266" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/zh-TW/docs/Web/API/Element" target="_top"><rect x="266" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="303.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Element</text></a><polyline points="341,25  351,20  351,30  341,25" stroke="#D4DDE4" fill="none"/><line x1="351" y1="25" x2="381" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLElement" target="_top"><rect x="381" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="436" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLElement</text></a><polyline points="491,25  501,20  501,30  491,25" stroke="#D4DDE4" fill="none"/><line x1="501" y1="25" x2="509" y2="25" stroke="#D4DDE4"/><line x1="509" y1="25" x2="509" y2="90" stroke="#D4DDE4"/><line x1="509" y1="90" x2="492" y2="90" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLImageElement" target="_top"><rect x="331" y="65" width="160" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="411" y="94" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLImageElement</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

屬性

Inherits properties from its parent, HTMLElement.

HTMLImageElement.align

Is a DOMString indicating the alignment of the image with respect to the surrounding context.

HTMLImageElement.alt

Is a DOMString that reflects the alt HTML attribute,  thus indicating fallback context for the image.

HTMLImageElement.border

Is a DOMString that is responsible for the width of the border surrounding the image. This is now deprecated and the CSS border property should be used instead.

HTMLImageElement.complete Read only

Returns a Boolean that is true if the browser has finished fetching the image, whether successful or not. It also shows true, if the image has no src value.

HTMLImageElement.crossOrigin

Is a DOMString representing the CORS setting for this image element. See CORS settings attributes for further details.

HTMLImageElement.currentSrc Read only

Returns a DOMString representing the URL to the currently displayed image (which may change, for example in response to media queries).

HTMLImageElement.height

一個反映了 HTML img 元素之 height 屬性的無符號（unsigned）整數，表示圖片經渲染後的高度（CSS pixels）。

HTMLImageElement.hspace

Is a long representing the space on either side of the image.

HTMLImageElement.isMap

Is a Boolean that reflects the ismap HTML attribute, indicating that the image is part of a server-side image map.

HTMLImageElement.longDesc

Is a DOMString representing the URI of a long description of the image.

HTMLImageElement.lowSrc

Is a DOMString that refers to a low-quality (but faster to load) copy of the image.

HTMLImageElement.name

Is a DOMString representing the name of the element.

HTMLImageElement.naturalHeight Read only

回傳一個代表圖片固有高度（CSS pixels）的無符號（unsigned）整數，如果無法取得則回傳 0。

HTMLImageElement.naturalWidth Read only

回傳一個代表圖片固有寬度（CSS pixels）的無符號（unsigned）整數，如果無法取得則回傳 0。

HTMLImageElement.referrerPolicy

Is a DOMString that reflects the referrerpolicy HTML attribute indicating which referrer to use in order to fetch the image.

HTMLImageElement.src

Is a DOMString that reflects the src HTML attribute, containing the full URL of the image including base URI.

HTMLImageElement.sizes

Is a DOMString reflecting the sizes HTML attribute.

HTMLImageElement.srcset

Is a DOMString reflecting the srcset HTML attribute, containing a list of candidate images, separated by a comma (',', U+002C COMMA). A candidate image is a URL followed by a 'w' with the width of the images, or an 'x' followed by the pixel density.

HTMLImageElement.useMap

Is a DOMString that reflects the usemap HTML attribute, containing a partial URL of a map element.

HTMLImageElement.vspace

Is a long representing the space above and below the image.

HTMLImageElement.width

一個反映了 HTML img 元素之 width 屬性的無符號（unsigned）整數，表示圖片經渲染後的寬度（CSS pixels）。

HTMLImageElement.x Read only

Returns a long representing the horizontal offset from the nearest layer. This property mimics an old Netscape 4 behavior.

HTMLImageElement.y Read only

Returns a long representing the vertical offset from the nearest layer. This property is also similar to behavior of an old Netscape 4.

方法

Inherits properties from its parent, HTMLElement.

Image()

The Image() constructor, taking two optional unsigned long, which are the width and the height of the resource, creates an instance of HTMLImageElement , not inserted in a DOM tree.

Errors

If an error occurs while trying to load or render the image, and an onerror event handler has been configured to handle the error event, that event handler will get called. This can happen in a number of situations, including:

• The src attribute is empty or null.
• The specified src URL is the same as the URL of the page the user is currently on.
• The specified image is corrupted in some way that prevents it from being loaded.
• The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the <img> element's attributes.
• The specified image is in a format not supported by the user agent.

範例

var img1 = new Image(); // HTML5 Constructor
img1.src = 'image1.png';
img1.alt = 'alt';
document.body.appendChild(img1);

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

規範

瀏覽器相容性

[1] Though, these x and y properties were removed in Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4) but later, they were restored in Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11) for compatibility reasons.

[2] This feature is behind the dom.image.srcset.enabled preference, defaulting to false.

[3] This feature is behind the dom.image.picture.enabled preference, defaulting to false.

[4] IE reports false for broken images.

[5] May also be supported in earlier versions.

See also

• The HTML element implementing this interface: <img>