HTMLImageElement

HTMLImageElement interface represents an HTML <img> element, providing the properties and methods used to manipulate image elements.

构造函数

Image()
Image() constructor creates and returns a new HTMLImageElement object representing an HTML <img> element which is not attached to any DOM tree. It accepts optional width and height parameters. When called without parameters, new Image() is equivalent to calling document.createElement("img") .

特性

Inherits properties from its parent, HTMLElement .

HTMLImageElement.alt
A DOMString that reflects the alt HTML attribute, thus indicating the alternate fallback content to be displayed if the image has not been loaded.
HTMLImageElement.complete 只读
返回 Boolean that is true if the browser has finished fetching the image, whether successful or not. That means this value is also true if the image has no src value indicating an image to load.
HTMLImageElement.crossOrigin
A DOMString specifying the CORS setting for this image element. See CORS settings attributes for further details. This may be null if CORS is not used.
HTMLImageElement.currentSrc 只读
返回 USVString representing the URL from which the currently displayed image was loaded. This may change as the image is adjusted due to changing conditions, as directed by any media queries which are in place.
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
An integer value that reflects the height HTML attribute, indicating the rendered height of the image in CSS pixels.
HTMLImageElement.isMap
A Boolean that reflects the ismap HTML attribute, indicating that the image is part of a server-side image map. 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.loading
A DOMString providing a hint to the browser used to optimize loading the document by determining whether to load the image immediately ( eager ) or on an as-needed basis ( lazy ).
HTMLImageElement.naturalHeight 只读
Returns an integer value representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows 0 . This is the height the image would be if it were rendered at its natural full size.
HTMLImageElement.naturalWidth 只读
An integer value representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show 0 . This is the width the image would be if it were rendered at its natural full size.
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
A USVString that reflects the src HTML attribute, which contains the full URL of the image including base URI. You can load a different image into the element by changing the URL in the src 属性。
HTMLImageElement.srcset
A USVString reflecting the srcset HTML attribute. This specifies a list of candidate images, separated by commas ( ',', U+002C COMMA ). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the srcset page for specifics on the format of the size substring.
HTMLImageElement.useMap
A DOMString reflecting the usemap HTML attribute, containing the page-local URL of the <map> element describing the image map to use. The page-local URL is a pound (hash) symbol ( # ) followed by the ID of the <map> element, such as #my-map-element <map> in turn contains <area> elements indicating the clickable areas in the image.
HTMLImageElement.width
An integer value that reflects the width HTML attribute, indicating the rendered width of the image in CSS pixels.
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
A DOMString indicating the alignment of the image with respect to the surrounding context. The possible values are "left" , "right" , "justify" ,和 "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
A DOMString which defines the width of the border surrounding the image. This is deprecated; use the CSS border property instead.
HTMLImageElement.hspace
An integer value which specifies the amount of space (in pixels) to leave empty on the left and right sides of the image.
HTMLImageElement.longDesc
A 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
A 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
A DOMString representing the name of the element.
HTMLImageElement.vspace
An integer value specifying the amount of empty space, in pixels, to leave above and below the image.

方法

Inherits properties from its parent, HTMLElement .

HTMLImageElement.decode()
返回 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.

错误

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:

  • 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(); // Image 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);
					

规范

规范 状态 Comment
CSS Object Model (CSSOM) View Module
The definition of 'Extensions to HTMLImageElement' in that specification.
工作草案 添加 x and y 特性。
HTML Living Standard
The definition of 'HTMLImageElement' in that specification.
实时标准 The following properties have been added: srcset , currentSrc and sizes .
HTML5
The definition of 'HTMLImageElement' in that specification.
Recommendation A constructor (with 2 optional parameters) has been added.
The following properties are now obsolete: name , border , align , hspace , vspace ,和 longdesc .
The following properties are now unsigned long , instead of long : height ,和 width .
The following properties have been added: crossorigin , naturalWidth , naturalHeight ,和 complete .
Document Object Model (DOM) Level 2 HTML Specification
The definition of 'HTMLImgElement' in that specification.
Obsolete lowSrc property has been removed.
The following properties are now long , instead of DOMString : height , width , hspace ,和 vspace .
Document Object Model (DOM) Level 1 Specification
The definition of 'HTMLImgElement' in that specification.
Obsolete 初始定义。

浏览器兼容性

更新 GitHub 上的兼容性数据
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
HTMLImageElement Chrome 1 Edge 12 Firefox 1 IE 8 Opera 8 Safari 3 WebView Android 1 Chrome Android 18 Firefox Android 4 Opera Android 10.1 Safari iOS 1 Samsung Internet Android 1.0
Image() 构造函数 Chrome 1 Edge 12 Firefox 1 IE 8 Opera 8 Safari 10.1 WebView Android 1 Chrome Android 18 Firefox Android 4 Opera Android ? Safari iOS 1 Samsung Internet Android 1.0
align Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
alt Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
border Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
complete Chrome 1 Edge 12 Firefox Yes IE 8
注意事项
8
注意事项
IE reports false for broken images.
Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
crossOrigin Chrome 13 Edge 12 Firefox Yes IE 9 Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
currentSrc
Chrome 45 Edge 13 Firefox 38
38
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 Opera Yes Safari 10.1 WebView Android 45 Chrome Android 45 Firefox Android 38
38
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 Safari iOS 10.3 Samsung Internet Android 5.0
decode() Chrome 64 Edge ≤79 Firefox 68 IE ? Opera Yes Safari 11.1 WebView Android 64 Chrome Android 64 Firefox Android 68 Opera Android ? Safari iOS 11.3 Samsung Internet Android 9.0
decoding Chrome 65 Edge ≤79 Firefox 63 IE 不支持 No Opera Yes Safari 11.1 WebView Android 65 Chrome Android 65 Firefox Android 63 Opera Android ? Safari iOS 11.3 Samsung Internet Android 9.0
error event Chrome 不支持 No Edge 不支持 No Firefox 51
注意事项
51
注意事项
May also be supported in earlier versions.
IE 不支持 No Opera Yes Safari Yes WebView Android 不支持 No Chrome Android 不支持 No Firefox Android 51 Opera Android Yes Safari iOS Yes Samsung Internet Android 不支持 No
height Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
hspace Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
isMap Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
loading
Chrome 76 Edge 79 Firefox 75 IE 不支持 No Opera 63 Safari 不支持 No
注意事项
No
注意事项
bug 196698
WebView Android 不支持 No Chrome Android 76 Firefox Android 不支持 No Opera Android 54 Safari iOS 不支持 No
注意事项
No
注意事项
bug 196698
Samsung Internet Android 不支持 No
longDesc Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
lowSrc Chrome 1 Edge ≤18 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android Yes
name Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
naturalHeight Chrome 1 Edge 12 Firefox Yes IE 9 Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
naturalWidth Chrome 1 Edge 12 Firefox Yes IE 9 Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android ? Safari iOS Yes Samsung Internet Android Yes
onerror Chrome 不支持 No Edge 不支持 No Firefox 51
注意事项
51
注意事项
May also be supported in earlier versions.
IE 不支持 No Opera Yes Safari Yes WebView Android 不支持 No Chrome Android 不支持 No Firefox Android 51 Opera Android Yes Safari iOS Yes Samsung Internet Android 不支持 No
referrerPolicy Chrome 51 Edge 79 Firefox 50 IE 不支持 No Opera 38 Safari 11.1 WebView Android 51 Chrome Android 51 Firefox Android 50 Opera Android 41 Safari iOS 不支持 No Samsung Internet Android 5.0
sizes
Chrome 45 Edge 13 Firefox 38
38
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 Opera Yes Safari 不支持 No WebView Android 45 Chrome Android 45 Firefox Android 38
38
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 Safari iOS 不支持 No Samsung Internet Android 5.0
src Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
srcset
Chrome 34 Edge 12 Firefox 38
38
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 Opera 21 Safari 8 WebView Android 37 Chrome Android 34 Firefox Android 38
38
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 Safari iOS 8 Samsung Internet Android 2.0
useMap Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
vspace Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
width Chrome 1 Edge 12 Firefox Yes IE ? Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android Yes Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
x Chrome 1 Edge 12 Firefox 14
14
? — 7
IE 不支持 No Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android 14
14
? — 7
Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
y Chrome 1 Edge 12 Firefox 14
14
? — 7
IE 不支持 No Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android 14
14
? — 7
Opera Android Yes Safari iOS Yes Samsung Internet Android Yes

图例

完整支持
完整支持
不支持
不支持
兼容性未知
兼容性未知
实验。期望将来行为有所改变。
实验。期望将来行为有所改变。
见实现注意事项。
用户必须明确启用此特征。
用户必须明确启用此特征。

另请参阅

  • The HTML element implementing this interface: <img>
  1. HTMLImageElement
  2. 构造函数
    1. Image()
  3. 特性
    1. align
    2. alt
    3. border
    4. complete
    5. crossOrigin
    6. currentSrc
    7. decoding
    8. height
    9. hspace
    10. loading
    11. longDesc
    12. lowSrc
    13. name
    14. naturalWidth
    15. referrerPolicy
    16. sizes
    17. srcset
    18. useMap
    19. vspace
    20. width
  4. 方法
    1. decode()
  5. 继承:
    1. HTMLElement
    2. Element
    3. Node
    4. EventTarget
  6. Related pages for HTML DOM
    1. BeforeUnloadEvent
    2. DOMStringMap
    3. ErrorEvent
    4. GlobalEventHandlers
    5. HTMLAnchorElement
    6. HTMLAreaElement
    7. HTMLAudioElement
    8. HTMLBRElement
    9. HTMLBaseElement
    10. HTMLBaseFontElement
    11. HTMLBodyElement
    12. HTMLButtonElement
    13. HTMLCanvasElement
    14. HTMLContentElement
    15. HTMLDListElement
    16. HTMLDataElement
    17. HTMLDataListElement
    18. HTMLDialogElement
    19. HTMLDivElement
    20. HTMLDocument
    21. HTMLElement
    22. HTMLEmbedElement
    23. HTMLFieldSetElement
    24. HTMLFormControlsCollection
    25. HTMLFormElement
    26. HTMLFrameSetElement
    27. HTMLHRElement
    28. HTMLHeadElement
    29. HTMLHeadingElement
    30. HTMLHtmlElement
    31. HTMLIFrameElement
    32. HTMLInputElement
    33. HTMLIsIndexElement
    34. HTMLKeygenElement
    35. HTMLLIElement
    36. HTMLLabelElement
    37. HTMLLegendElement
    38. HTMLLinkElement
    39. HTMLMapElement
    40. HTMLMediaElement
    41. HTMLMetaElement
    42. HTMLMeterElement
    43. HTMLModElement
    44. HTMLOListElement
    45. HTMLObjectElement
    46. HTMLOptGroupElement
    47. HTMLOptionElement
    48. HTMLOptionsCollection
    49. HTMLOutputElement
    50. HTMLParagraphElement
    51. HTMLParamElement
    52. HTMLPictureElement
    53. HTMLPreElement
    54. HTMLProgressElement
    55. HTMLQuoteElement
    56. HTMLScriptElement
    57. HTMLSelectElement
    58. HTMLShadowElement
    59. HTMLSourceElement
    60. HTMLSpanElement
    61. HTMLStyleElement
    62. HTMLTableCaptionElement
    63. HTMLTableCellElement
    64. HTMLTableColElement
    65. HTMLTableDataCellElement
    66. HTMLTableElement
    67. HTMLTableHeaderCellElement
    68. HTMLTableRowElement
    69. HTMLTableSectionElement
    70. HTMLTemplateElement
    71. HTMLTextAreaElement
    72. HTMLTimeElement
    73. HTMLTitleElement
    74. HTMLTrackElement
    75. HTMLUListElement
    76. HTMLUnknownElement
    77. HTMLVideoElement
    78. HashChangeEvent
    79. History
    80. ImageData
    81. Location
    82. MessageChannel
    83. MessageEvent
    84. MessagePort
    85. Navigator
    86. NavigatorGeolocation
    87. NavigatorID
    88. NavigatorLanguage
    89. NavigatorOnLine
    90. NavigatorPlugins
    91. PageTransitionEvent
    92. Plugin
    93. PluginArray
    94. PopStateEvent
    95. PortCollection
    96. PromiseRejectionEvent
    97. RadioNodeList
    98. Transferable
    99. ValidityState
    100. Window
    101. WindowBase64
    102. WindowEventHandlers
    103. WindowTimers