HTMLImageElement

基线广泛可用

此功能已得到完善，可在许多设备和浏览器版本中使用。它自以下时间起在所有浏览器中均可用 2015 年 7 月.

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

构造函数

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

实例属性

继承自其父级 HTMLElement 的属性。

HTMLImageElement.alt: 一个字符串，反映 alt HTML 属性，因此指示如果图像未加载则要显示的备用回退内容。
HTMLImageElement.attributionSrc 安全上下文实验性: 以编程方式获取和设置 attributionsrc 属性在 <img> 元素上，反映该属性的值。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> 元素和相应的 <map> 指定，其中包含 <area> 元素，指示图像中可点击的区域。图像必须包含在 <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 是一个井号 (#)，后跟 <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> 元素的属性中指定任何尺寸。
指定的图像格式不受用户代理支持。

示例

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

规范

规范
HTML 标准 # htmlimageelement

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅

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