---
title: HTMLImageElement
slug: Web/API/HTMLImageElement
translation_of: Web/API/HTMLImageElement
---
<div>{{ APIRef("HTML DOM") }}</div>

<p><span class="seoSummary"><strong><code>HTMLImageElement</code></strong> 接口提供了特别的属性和方法 (在常规的 {{domxref("HTMLElement")}}之外，它也能通过继承使用)来操纵 {{HTMLElement("img")}} 元素的布局和图像。</span></p>

<p>{{InheritanceDiagram(600, 120)}}</p>

<h2 id="Constructor">Constructor</h2>

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

<h2 id="属性">属性</h2>

<p><em>从它的父元素 {{domxref("HTMLElement")}} 继承的属性。</em></p>

<dl>
 <dt>{{domxref("HTMLImageElement.alt")}}</dt>
 <dd>一个 {{domxref("DOMString")}} 表示 HTML 属性 {{htmlattrxref("alt", "img")}}，表明图像的后备描述内容，会在图像无法加载时显示。</dd>
 <dt>{{domxref("HTMLImageElement.complete")}} {{readonlyInline}}</dt>
 <dd>返回一个 {{domxref("Boolean")}} 如果浏览器已经下载完毕，并且图像是<a href="/en-US/docs/HTML/Element/Img#Image_Format" title="HTML/Element/Img#Image Format">受支持的图片类型</a>、解码的过程中没有发生错误，则返回 <code>true</code>。That means this value is also <code>true</code> if the image has no {{domxref("HTMLImageElement.src", "src")}} value indicating an image to load.</dd>
 <dt>{{domxref("HTMLImageElement.crossOrigin")}}</dt>
 <dd>一个 {{domxref("DOMString")}} 表示这个img元素的 CORS 设置。参考 <a href="/en-US/docs/HTML/CORS_settings_attributes" title="HTML/CORS settings attributes">CORS settings attributes</a>。This may be <code>null</code> if CORS is not used.</dd>
 <dt>{{domxref("HTMLImageElement.currentSrc")}} {{readonlyInline}}</dt>
 <dd>返回一个 {{domxref("DOMString")}}  表示加载当前显示的图像的URL。<br>
 这可能会改变，因为图像是调整，由于不断变化的条件，由任何 <a href="/zh-CN/docs/Web/CSS/Media_Queries">media queries</a> 的地方。</dd>
 <dt>{{domxref("HTMLImageElement.decoding")}}</dt>
 <dd>An optional {{domxref("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: <code>sync</code> to decode the image synchronously, <code>async</code> to decode it asynchronously, or <code>auto</code> to indicate no preference (which is the default). Read the {{domxref("HTMLImageElement.decoding", "decoding")}} page for details on the implications of this property's values.</dd>
 <dt>{{domxref("HTMLImageElement.height")}}</dt>
 <dd>一个整数，表示 HTML 属性 {{htmlattrxref("height", "img")}}，说明了图像在 CSS 像素中渲染的高度。</dd>
 <dt>{{domxref("HTMLImageElement.isMap")}}</dt>
 <dd>一个 {{domxref("Boolean")}} 表示 HTML 属性 {{htmlattrxref("ismap", "img")}}，说明了图像是某个服务器端图像映射的一部分。This is different from a client-side image map, specified using an <code>&lt;img&gt;</code> element and a corresponding {{HTMLElement("map")}} which contains {{HTMLElement("area")}} elements indicating the clickable areas in the image. The image <em>must</em> be contained within an {{HTMLElement("a")}} element; see the <code>ismap</code> page for details.</dd>
 <dt>{{domxref("HTMLImageElement.naturalHeight")}} {{readonlyInline}}</dt>
 <dd>返回一个整数，如果可用的话，表明图像在 CSS 中固有的高度，单位为像素；否则返回 <code>0</code>。如果图片是以其原来的大小渲染，则此值等于图片的高度。</dd>
 <dt>{{domxref("HTMLImageElement.naturalWidth")}} {{readonlyInline}}</dt>
 <dd>返回一个整数，如果可用的话，表明图像在 CSS 中固有的宽度，单位为像素；否则返回 <code>0</code>。如果图片是以其原来的大小渲染，则此值等于图片的宽度。</dd>
 <dt>{{domxref("HTMLImageElement.referrerPolicy")}}</dt>
 <dd>A {{domxref("DOMString")}} that reflects the {{htmlattrxref("referrerpolicy", "img")}} HTML attribute, which tells the {{Glossary("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.</dd>
 <dt>{{domxref("HTMLImageElement.sizes")}} {{experimental_inline}}</dt>
 <dd>A {{domxref("DOMString")}} reflecting the {{htmlattrxref("sizes", "img")}} 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 {{domxref("HTMLImageElement.sizes", "sizes")}} page for details on the format of this string.</dd>
 <dt>{{domxref("HTMLImageElement.src")}}</dt>
 <dd>一个 {{domxref("DOMString")}} 表示 HTML 属性 {{htmlattrxref("src", "img")}}，包含图像的完整的 URL，包含图像的基础 URL。</dd>
 <dt>{{domxref("HTMLImageElement.srcset")}} {{experimental_inline}}</dt>
 <dd>一个 {{domxref("DOMString")}} 表示 HTML 属性 {{htmlattrxref("srcset", "img")}}，包含了候选图像列表，用逗号分隔（<code>',', U+002C COMMA</code>）。一个候选的图像是一个URL 跟着一个 <code>'w'</code> 表示图像的宽度，或者一个 <code>'x'</code> 表示像素密度.</dd>
 <dt>{{domxref("HTMLImageElement.useMap")}}</dt>
 <dd>一个 {{domxref("DOMString")}} 表示 HTML 属性 {{htmlattrxref("usemap", "img")}}，包含一个 {{HTMLElement("map")}} 元素的页面本地 URL。The page-local URL is a pound (hash) symbol (<code>#</code>) followed by the ID of the <code>&lt;map&gt;</code> element, such as <code>#my-map-element</code>. The <code>&lt;map&gt;</code> in turn contains {{HTMLElement("area")}} elements indicating the clickable areas in the image.</dd>
 <dt>{{domxref("HTMLImageElement.width")}}</dt>
 <dd>一个整数，表示 HTML 属性 {{htmlattrxref("width", "img")}}，说明图像在 CSS 像素中渲染的宽度。</dd>
 <dt>{{domxref("HTMLImageElement.x")}} {{readonlyInline}}{{experimental_inline}}</dt>
 <dd>An integer indicating the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the {{HTMLElement("html")}} element's containing block.</dd>
 <dt>{{domxref("HTMLImageElement.y")}} {{readonlyInline}} {{experimental_inline}}</dt>
 <dd>The integer vertical offset of the top border edge of the image's CSS layout box relative to the origin of the {{HTMLElement("html")}} element's containing block.</dd>
</dl>

<h2 id="已废弃的属性">已废弃的属性</h2>

<dl>
 <dt>{{domxref("HTMLImageElement.align")}} {{obsolete_inline}}</dt>
 <dd>一个 {{domxref("DOMString")}}，表示图像如何与它周围的内容对齐。The possible values are <code>"left"</code>, <code>"right"</code>, <code>"justify"</code>, and <code>"center"</code>. This is obsolete; you should instead use CSS (such as {{cssxref("text-align")}}, which works with images despite its name) to specify the alignment.</dd>
 <dt>{{domxref("HTMLImageElement.border")}} {{obsolete_inline}}</dt>
 <dd>一个 {{domxref("DOMString")}}，表示图像边框的宽度。此属性已被弃用，应该用 CSS {{cssxref("border")}} 属性来代替它。</dd>
 <dt>{{domxref("HTMLImageElement.hspace")}} {{obsolete_inline}}</dt>
 <dd>一个整数值，指定图像左右的留白，单位为像素。</dd>
 <dt>{{domxref("HTMLImageElement.longDesc")}} {{obsolete_inline}}</dt>
 <dd>一个 {{domxref("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 <code>&lt;img&gt;</code> inside an {{HTMLElement("a")}} element defining the hyperlink.</dd>
 <dt>{{domxref("HTMLImageElement.lowSrc")}} {{obsolete_inline}}</dt>
 <dd>一个 {{domxref("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.</dd>
 <dt>{{domxref("HTMLImageElement.name")}} {{obsolete_inline}}</dt>
 <dd>一个 {{domxref("DOMString")}}，representing the name of the element.</dd>
 <dt>{{domxref("HTMLImageElement.vspace")}} {{obsolete_inline}}</dt>
 <dd>一个整数值，指定图像上下的留白，单位为像素。</dd>
</dl>

<h2 id="方法">方法</h2>

<p><em>从它的父元素 {{domxref("HTMLElement")}} 继承的方法。</em></p>

<dl>
 <dt>{{domxref("HTMLImageElement.decode()")}}</dt>
 <dd>Returns a {{jsxref("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.</dd>
</dl>

<h2 id="错误">错误</h2>

<ul>
 <li>The {{htmlattrxref("src", "img")}} attribute is empty or <code>null</code>.</li>
 <li>The specified <code>src</code> URL is the same as the URL of the page the user is currently on.</li>
 <li>The specified image is corrupted in some way that prevents it from being loaded.</li>
 <li>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 <code>&lt;img&gt;</code> element's attributes.</li>
 <li>The specified image is in a format not supported by the {{Glossary("user agent")}}.</li>
</ul>

<dl>
 <dd>If an error occurs while trying to load or render the image, and an {{htmlattrxref("onerror")}} event handler has been configured to handle the {{event("error")}} event, that event handler will get called. This can happen in a number of situations, including:</dd>
</dl>

<h2 id="例子">例子</h2>

<pre class="brush: js">var img1 = new Image(); // Image 构造器
img1.src = 'image1.png';
img1.alt = 'alt';
document.body.appendChild(img1);

var img2 = document.createElement('img'); // 使用 DOM <a href="http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/html/nsIDOMHTMLImageElement.idl" title="http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/html/nsIDOMHTMLImageElement.idl">HTMLImageElement</a>
img2.src = 'image2.jpg';
img2.alt = 'alt text';
document.body.appendChild(img2);

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

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">规范</th>
   <th scope="col">状态</th>
   <th scope="col">备注</th>
  </tr>
  <tr>
   <td>{{SpecName("CSSOM View", "#excensions-to-the-htmlimageelement-interface", "Extensions to HTMLImageElement")}}</td>
   <td>{{Spec2('CSSOM View')}}</td>
   <td><font face="Open Sans, Arial, sans-serif">添加 </font><code>x</code> 和 <code>y</code> 属性。</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', "embedded-content.html#the-img-element", "HTMLImageElement")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>以下属性被添加了：<code>srcset</code>、<code>currentSrc</code> 和 <code>sizes</code>。</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5 W3C', "embedded-content-0.html#the-img-element", "HTMLImageElement")}}</td>
   <td>{{Spec2('HTML5 W3C')}}</td>
   <td>一个构造器（带有 2 个可选的参数）已经被添加.<br>
    以下属性已被弃用：<code>name</code>、<code>border</code>、<code>align</code>、<code>hspace</code>、<code>vspace</code>，和 <code>longdesc</code>.<br>
    以下属性现在是 <code>unsigned long</code>, 类型，不再是 <code>long</code> 类型: <code>height</code> 和 <code>width</code>。<br>
    添加了以下属性：<code>crossorigin</code>, <code>naturalWidth</code>, <code>naturalHeight</code>, 和<code>complete</code>.</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 HTML', 'html.html#ID-17701901', 'HTMLImgElement')}}</td>
   <td>{{Spec2('DOM2 HTML')}}</td>
   <td>The <code>lowSrc</code> 属性已被移除。<br>
    以下属性现在是 <code>long</code> 类型了，而不是 <code>DOMString</code> 类型了： <code>height</code>、<code>width</code>、<code>hspace</code>，和 <code>vspace</code>。</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM1', 'level-one-html.html#ID-17701901', 'HTMLImgElement')}}</td>
   <td>{{Spec2('DOM1')}}</td>
   <td>初始定义。</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>



<p>{{Compat("api.HTMLImageElement")}}</p>

<h2 id="参见">参见</h2>

<ul>
 <li>实现了这个接口的 HTML 元素：{{HTMLElement("img")}}</li>
</ul>