HTMLImageElement

翻译不完整。 请帮助我们翻译这篇文章!

HTMLImageElement 接口提供了特别的属性和方法 (在常规的 HTMLElement之外,它也能通过继承使用)来操纵 <img> 元素的布局和图像。

Constructor

Image()
Image() 构造器,带有两个可选的参数,分别表示资源的宽度和高度,创建了一个尚未被插入 DOM 树中的 HTMLImageElement 实例。When called without parameters, new Image() is equivalent to calling document.createElement("img").

属性

从它的父元素 HTMLElement 继承的属性。

HTMLImageElement.alt
一个 DOMString 表示 HTML 属性 alt,表明图像的后备描述内容,会在图像无法加载时显示。
HTMLImageElement.complete 只读
返回一个 Boolean 如果浏览器已经下载完毕,并且图像是受支持的图片类型、解码的过程中没有发生错误,则返回 true。That means this value is also true if the image has no src value indicating an image to load.
HTMLImageElement.crossOrigin
一个 DOMString 表示这个img元素的 CORS 设置。参考 CORS settings attributes。This may be null if CORS is not used.
HTMLImageElement.currentSrc 只读
返回一个 DOMString  表示加载当前显示的图像的URL。
这可能会改变,因为图像是调整,由于不断变化的条件,由任何 media queries 的地方。
HTMLImageElement.decoding
An optional DOMString representing a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: sync to decode the image synchronously, async to decode it asynchronously, or auto to indicate no preference (which is the default). Read the decoding page for details on the implications of this property's values.
HTMLImageElement.height
一个整数,表示 HTML 属性 height,说明了图像在 CSS 像素中渲染的高度。
HTMLImageElement.isMap
一个 Boolean 表示 HTML 属性 ismap,说明了图像是某个服务器端图像映射的一部分。This is different from a client-side image map, specified using an <img> element and a corresponding <map> which contains <area> elements indicating the clickable areas in the image. The image must be contained within an <a> element; see the ismap page for details.
HTMLImageElement.naturalHeight 只读
返回一个整数,如果可用的话,表明图像在 CSS 中固有的高度,单位为像素;否则返回 0。如果图片是以其原来的大小渲染,则此值等于图片的高度。
HTMLImageElement.naturalWidth 只读
返回一个整数,如果可用的话,表明图像在 CSS 中固有的宽度,单位为像素;否则返回 0。如果图片是以其原来的大小渲染,则此值等于图片的宽度。
HTMLImageElement.referrerPolicy
A DOMString that reflects the referrerpolicy HTML attribute, which tells the user agent how to decide which referrer to use in order to fetch the image. Read this article for details on the possible values of this string.
HTMLImageElement.sizes
A DOMString reflecting the sizes HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the sizes page for details on the format of this string.
HTMLImageElement.src
一个 DOMString 表示 HTML 属性 src,包含图像的完整的 URL,包含图像的基础 URL。
HTMLImageElement.srcset
一个 DOMString 表示 HTML 属性 srcset,包含了候选图像列表,用逗号分隔(',', U+002C COMMA)。一个候选的图像是一个URL 跟着一个 'w' 表示图像的宽度,或者一个 'x' 表示像素密度.
HTMLImageElement.useMap
一个 DOMString 表示 HTML 属性 usemap,包含一个 <map> 元素的页面本地 URL。The page-local URL is a pound (hash) symbol (#) followed by the ID of the <map> element, such as #my-map-element. The <map> in turn contains <area> elements indicating the clickable areas in the image.
HTMLImageElement.width
一个整数,表示 HTML 属性 width,说明图像在 CSS 像素中渲染的宽度。
HTMLImageElement.x 只读
An integer indicating the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.
HTMLImageElement.y 只读
The integer vertical offset of the top border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.

已废弃的属性

HTMLImageElement.align
一个 DOMString,表示图像如何与它周围的内容对齐。The possible values are "left", "right", "justify", and "center". This is obsolete; you should instead use CSS (such as text-align, which works with images despite its name) to specify the alignment.
HTMLImageElement.border
一个 DOMString,表示图像边框的宽度。此属性已被弃用,应该用 CSS border 属性来代替它。
HTMLImageElement.hspace
一个整数值,指定图像左右的留白,单位为像素。
HTMLImageElement.longDesc
一个 USVString,specifying the URL at which a long description of the image's contents may be found. This is used to turn the image into a hyperlink automatically. Modern HTML should instead simply place an <img> inside an <a> element defining the hyperlink.
HTMLImageElement.lowSrc
一个 USVString,specifying the URL of a low-quality (but faster to load) version of the same image. This was once used by browsers under constrained network conditions or on slow devices.
HTMLImageElement.name
一个 DOMString,representing the name of the element.
HTMLImageElement.vspace
一个整数值,指定图像上下的留白,单位为像素。

方法

从它的父元素 HTMLElement 继承的方法。

HTMLImageElement.decode()
Returns a Promise that resolves when the image is decoded and it's safe to append the image to the DOM. This prevents rendering of the next frame from having to pause to decode the image, as would happen if an undecoded image were added to the DOM.

错误

  • 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.
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:

例子

var img1 = new Image(); // Image 构造器
img1.src = 'image1.png';
img1.alt = 'alt';
document.body.appendChild(img1);

var img2 = document.createElement('img'); // 使用 DOM HTMLImageElement
img2.src = 'image2.jpg';
img2.alt = 'alt text';
document.body.appendChild(img2);

// 使用文档中的第一个 img
alert(document.images[0].src);

规范

规范 状态 备注
CSS Object Model (CSSOM) View Module
Extensions to HTMLImageElement
Working Draft 添加 xy 属性。
HTML Living Standard
HTMLImageElement
Living Standard 以下属性被添加了:srcsetcurrentSrcsizes
HTML5
HTMLImageElement
Recommendation 一个构造器(带有 2 个可选的参数)已经被添加.
以下属性已被弃用:nameborderalignhspacevspace,和 longdesc.
以下属性现在是 unsigned long, 类型,不再是 long 类型: heightwidth
添加了以下属性:crossorigin, naturalWidth, naturalHeight, 和complete.
Document Object Model (DOM) Level 2 HTML Specification
HTMLImgElement
Obsolete The lowSrc 属性已被移除。
以下属性现在是 long 类型了,而不是 DOMString 类型了: heightwidthhspace,和 vspace
Document Object Model (DOM) Level 1 Specification
HTMLImgElement
Obsolete 初始定义。

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
HTMLImageElementChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 8Opera Full support 8Safari Full support 3WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0
Image() constructorChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 8Opera Full support 8Safari Full support 10.1WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android ? Safari iOS Full support 1Samsung Internet Android Full support 1.0
alignChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
altChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
borderChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
completeChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 8
Notes
Full support 8
Notes
Notes IE reports false for broken images.
Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
crossOriginChrome Full support 13Edge Full support 12Firefox Full support YesIE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
currentSrc
Experimental
Chrome Full support 45Edge Full support 13Firefox Full support 38
Full support 38
No support 32 — 52
Disabled
Disabled From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari Full support 10.1WebView Android Full support 45Chrome Android Full support 45Firefox Android Full support 38
Full support 38
No support 32 — 52
Disabled
Disabled From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS Full support 10.3Samsung Internet Android Full support 5.0
decode()Chrome Full support 64Edge Full support ≤79Firefox Full support 68IE ? Opera Full support YesSafari Full support 11.1WebView Android Full support 64Chrome Android Full support 64Firefox Android Full support 68Opera Android ? Safari iOS Full support 11.3Samsung Internet Android Full support 9.0
decodingChrome Full support 65Edge Full support ≤79Firefox Full support 63IE No support NoOpera Full support YesSafari Full support 11.1WebView Android Full support 65Chrome Android Full support 65Firefox Android Full support 63Opera Android ? Safari iOS Full support 11.3Samsung Internet Android Full support 9.0
error eventChrome No support NoEdge No support NoFirefox Full support 51
Notes
Full support 51
Notes
Notes May also be supported in earlier versions.
IE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android No support NoFirefox Android Full support 51Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android No support No
heightChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
hspaceChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
isMapChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
loading
Experimental
Chrome Full support 76Edge Full support 79Firefox Full support 75IE No support NoOpera Full support 63Safari No support No
Notes
No support No
Notes
Notes See bug 196698
WebView Android No support NoChrome Android Full support 76Firefox Android No support NoOpera Android Full support 54Safari iOS No support No
Notes
No support No
Notes
Notes See bug 196698
Samsung Internet Android No support No
longDescChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
lowSrcChrome Full support 1Edge Full support ≤18Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android Full support Yes
nameChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
naturalHeightChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
naturalWidthChrome Full support 1Edge Full support 12Firefox Full support YesIE Full support 9Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android ? Safari iOS Full support YesSamsung Internet Android Full support Yes
onerrorChrome No support NoEdge No support NoFirefox Full support 51
Notes
Full support 51
Notes
Notes May also be supported in earlier versions.
IE No support NoOpera Full support YesSafari Full support YesWebView Android No support NoChrome Android No support NoFirefox Android Full support 51Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android No support No
referrerPolicyChrome Full support 51Edge Full support 79Firefox Full support 50IE No support NoOpera Full support 38Safari Full support 11.1WebView Android Full support 51Chrome Android Full support 51Firefox Android Full support 50Opera Android Full support 41Safari iOS No support NoSamsung Internet Android Full support 5.0
sizes
Experimental
Chrome Full support 45Edge Full support 13Firefox Full support 38
Full support 38
No support 33 — 52
Disabled
Disabled From version 33 until version 52 (exclusive): this feature is behind the dom.image.picture.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android Full support 45Chrome Android Full support 45Firefox Android Full support 38
Full support 38
No support 33 — 52
Disabled
Disabled From version 33 until version 52 (exclusive): this feature is behind the dom.image.picture.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 5.0
srcChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
srcset
Experimental
Chrome Full support 34Edge Full support 12Firefox Full support 38
Full support 38
No support 32 — 52
Disabled
Disabled From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 21Safari Full support 8WebView Android Full support 37Chrome Android Full support 34Firefox Android Full support 38
Full support 38
No support 32 — 52
Disabled
Disabled From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android No support NoSafari iOS Full support 8Samsung Internet Android Full support 2.0
useMapChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
vspaceChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
widthChrome Full support 1Edge Full support 12Firefox Full support YesIE ? Opera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
xChrome Full support 1Edge Full support 12Firefox Full support 14
Full support 14
No support ? — 7
IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support 14
Full support 14
No support ? — 7
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
yChrome Full support 1Edge Full support 12Firefox Full support 14
Full support 14
No support ? — 7
IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support 14
Full support 14
No support ? — 7
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

参见

  • 实现了这个接口的 HTML 元素:<img>