1. Web
  2. Web API
  3. HTMLImageElement

HTMLImageElement

Baseline 广泛可用 *

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

* 此特性的某些部分可能存在不同级别的支持。

HTMLImageElement 接口表示一个 HTML <img> 元素，提供用于操作图像元素的属性和方法。

EventTarget Node Element HTMLElement HTMLImageElement

构造函数

Image()

Image() 构造函数创建并返回一个新的 HTMLImageElement 对象，该对象表示一个未附加到任何 DOM 树的 HTML <img> 元素。它接受可选的 width 和 height 参数。当不带参数调用时，new Image() 相当于调用 document.createElement('img')。

实例属性

继承自其父级 HTMLElement 的属性。

HTMLImageElement.alt

一个字符串，反映 alt HTML 属性，指示图像未加载时要显示的备用内容。

HTMLImageElement.attributionSrc 安全上下文

以编程方式获取和设置 <img> 元素的 attributionsrc 属性，反映该属性的值。attributionsrc 指定您希望浏览器在图像请求中发送 Attribution-Reporting-Eligible 标头。在服务器端，这用于触发在响应中发送 Attribution-Reporting-Register-Source 或 Attribution-Reporting-Register-Trigger 标头，以分别注册基于图像的归因源或归因触发器。

HTMLImageElement.complete 只读

返回一个布尔值，如果浏览器已完成获取图像（无论成功与否），则该值为 true。这意味着如果图像没有指示要加载图像的 src 值，则此值也为 true。

HTMLImageElement.crossOrigin

一个字符串，指定此图像元素的 CORS 设置。有关详细信息，请参阅 CORS 设置属性。如果未使用 CORS，则此值可能为 null。

HTMLImageElement.currentSrc 只读

返回一个字符串，表示当前显示的图像的加载 URL。根据任何现有的 媒体查询 的指示，当条件变化时，图像可能会随之调整，此值也可能发生变化。

HTMLImageElement.decoding

一个可选的字符串，表示浏览器应该如何解码图像的提示。如果提供了此值，则它必须是允许的可能值之一：sync 同步解码图像，async 异步解码图像，或 auto 表示没有偏好（这是默认值）。有关此属性值的含义的详细信息，请阅读 decoding 页面。

HTMLImageElement.fetchPriority

一个可选的字符串，表示浏览器应该如何相对于其他图像优先获取图像的提示。如果提供了此值，则它必须是允许的可能值之一：high 以高优先级获取，low 以低优先级获取，或 auto 表示没有偏好（这是默认值）。

HTMLImageElement.height

一个整数值，反映 height HTML 属性，指示图像在 CSS 像素中的渲染高度。

HTMLImageElement.isMap

一个布尔值，反映 ismap HTML 属性，指示图像是服务器端图像映射的一部分。这与客户端图像映射不同，客户端图像映射使用 <img> 元素和包含 <area> 元素（指示图像中的可点击区域）的相应 <map> 来指定。图像必须包含在 <a> 元素中；有关详细信息，请参阅 ismap 页面。

HTMLImageElement.loading

一个字符串，向浏览器提供提示，用于通过确定是立即加载图像（eager）还是按需加载（lazy）来优化文档加载。

HTMLImageElement.naturalHeight 只读

返回一个整数值，表示图像在 CSS 像素中的固有高度（如果可用）；否则显示 0。这是图像以其自然全尺寸渲染时的高度。

HTMLImageElement.naturalWidth 只读

一个整数值，表示图像在 CSS 像素中的固有宽度（如果可用）；否则将显示 0。这是图像以其自然全尺寸渲染时的宽度。

HTMLImageElement.referrerPolicy

一个字符串，反映 referrerpolicy HTML 属性，它告诉 用户代理 如何决定使用哪个引用者来获取图像。阅读本文以了解此字符串的可能值的详细信息。

HTMLImageElement.sizes

一个字符串，反映 sizes HTML 属性。此字符串指定图像的逗号分隔的条件大小列表；也就是说，对于给定的视口大小，将使用特定的图像大小。有关此字符串格式的详细信息，请阅读 sizes 页面上的文档。

HTMLImageElement.src

一个字符串，反映 src HTML 属性，其中包含图像的完整 URL，包括基本 URI。您可以通过更改 src 属性中的 URL 来将不同的图像加载到元素中。

HTMLImageElement.srcset

一个字符串，反映 srcset HTML 属性。这指定了一个候选图像列表，由逗号 (',', U+002C COMMA) 分隔。每个候选图像是一个 URL，后跟一个空格，再后跟一个特殊格式的字符串，指示图像的大小。大小可以指定为宽度或大小倍数。有关大小子字符串格式的详细信息，请阅读 srcset 页面。

HTMLImageElement.useMap

一个字符串，反映 usemap HTML 属性，其中包含描述要使用的图像映射的 <map> 元素的页面局部 URL。页面局部 URL 是一个井号 (hash) 符号 (#)，后跟 <map> 元素的 ID，例如 #my-map-element。<map> 反过来包含 <area> 元素，指示图像中的可点击区域。

HTMLImageElement.width

一个整数值，反映 width HTML 属性，指示图像在 CSS 像素中的渲染宽度。

HTMLImageElement.x 只读

一个整数，指示图像 CSS 布局框的左边框边缘相对于 <html> 元素的包含块原点的水平偏移量。

HTMLImageElement.y 只读

图像 CSS 布局框的顶部边框边缘相对于 <html> 元素的包含块原点的整数垂直偏移量。

已废弃的属性

HTMLImageElement.align

一个字符串，指示图像相对于周围上下文的对齐方式。可能的值是 "left"、"right"、"justify" 和 "center"。这已过时；您应该改用 CSS（例如 text-align，尽管其名称如此，但它适用于图像）来指定对齐方式。

HTMLImageElement.border

一个字符串，定义图像周围边框的宽度。这已弃用；请改用 CSS border 属性。

HTMLImageElement.hspace

一个整数值，指定图像左右两侧要留空的量（以像素为单位）。

HTMLImageElement.longDesc

一个字符串，指定可以找到图像内容长描述的 URL。这用于自动将图像转换为超链接。现代 HTML 应该将 <img> 放在定义超链接的 <a> 元素中。

HTMLImageElement.name

一个字符串，表示元素的名称。

HTMLImageElement.vspace

一个整数值，指定图像上方和下方要留空的像素量。

实例方法

继承自其父级 HTMLElement 的方法。

HTMLImageElement.decode()

返回一个 Promise，当图像被解码并且可以安全地将图像附加到 DOM 时，该 Promise 将解析。这可以防止在将未解码的图像添加到 DOM 时，下一帧的渲染暂停以解码图像。

错误

如果尝试加载或渲染图像时发生错误，并且已配置 onerror 事件处理程序来处理 error 事件，则将调用该事件处理程序。这可能发生在多种情况下，包括：

  • src 属性为空或 null。
  • 指定的 src URL 与用户当前所在的页面 URL 相同。
  • 指定的图像以某种方式损坏，导致无法加载。
  • 指定的图像元数据以某种方式损坏，导致无法检索其尺寸，并且在 <img> 元素的属性中未指定任何尺寸。
  • 指定的图像格式不受 用户代理 支持。

示例

创建和插入图像元素

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

获取宽度和高度

以下示例展示了 height 和 width 属性与不同尺寸图像的用法：

html
<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>
js
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;

规范

规范
HTML
# htmlimageelement

浏览器兼容性

另见

  • 实现此接口的 HTML 元素：<img>

帮助改进 MDN

了解如何贡献

此页面由 MDN 贡献者 上次修改于 。

在 GitHub 上查看此页面 • 报告此内容的问题