<img>: 图片嵌入元素

以上示例显示了 <img> 元素的使用方法

• src 属性是必需的，它包含要嵌入的图像的路径。
• alt 属性保存图像的文本替换，这是强制性的，并且对于辅助功能非常有用——屏幕阅读器将其属性值读给用户，以便他们知道图像的含义。如果图像由于某种原因无法加载，则 alt 文本也会显示在页面上：例如，网络错误、内容阻止或链接失效。

还有许多其他属性可以实现各种目的

• Referrer/CORS 用于安全和隐私控制：请参阅 crossorigin 和 referrerpolicy。
• 同时使用 width 和 height 设置图像的固有大小，使其在加载前占用空间，从而减轻内容布局偏移。
• 使用 sizes 和 srcset 提供响应式图像提示（另请参阅 <picture> 元素和我们的 响应式图像 教程）。

HTML 标准未列出要支持的图像格式，因此 用户代理 可能支持不同的格式。

Web 上最常用的图像文件格式有：

• APNG（动画便携式网络图形）—— 无损动画序列的不错选择（GIF 的性能较差）
• AVIF（AV1 图像文件格式）—— 由于高性能，图像和动画图像的不错选择。
• GIF（图形交换格式）—— 简单图像和动画的不错选择。
• JPEG（联合图像专家组图像）—— 静止图像的有损压缩的不错选择（目前最流行）。
• PNG（便携式网络图形）—— 静止图像的无损压缩的不错选择（质量略优于 JPEG）。
• SVG（可缩放矢量图形）—— 矢量图像格式。用于必须以不同尺寸精确绘制的图像。
• WebP（Web 图片格式）—— 图像和动画图像的绝佳选择

建议使用 WebP 和 AVIF 等格式，因为它们在静止图像和动画图像方面都比 PNG、JPEG、GIF 具有更好的性能。

对于必须以不同尺寸精确绘制的图像，SVG 仍然是推荐的格式。

如果在加载或渲染图像时发生错误，并且已为 error 事件设置了 onerror 事件处理程序，则将调用该事件处理程序。这可能发生在以下几种情况下：

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

此元素包含全局属性。

alt

定义可在页面中替换图像的文本。

注意：浏览器并不总是显示图像。在多种情况下，浏览器可能不会显示图像，例如

• 非视觉浏览器（例如视障人士使用的浏览器）
• 用户选择不显示图像（节省带宽、出于隐私原因）
• 图像无效或不支持的类型

在这些情况下，浏览器可能会用元素的alt属性中的文本替换图像。出于这些以及其他原因，请尽可能为alt提供有用的值。

将此属性设置为空字符串（alt=""）表示此图像不是内容的关键部分（它是装饰或跟踪像素），非视觉浏览器可能会将其从渲染中省略。如果alt属性为空且图像未能显示，视觉浏览器也会隐藏损坏的图像图标。

此属性还用于将图像复制粘贴到文本中或将链接的图像保存到书签中。

attributionsrc 实验性

指定您希望浏览器在发送图像请求时同时发送Attribution-Reporting-Eligible标头。

在服务器端，这用于触发在响应中发送Attribution-Reporting-Register-Source或Attribution-Reporting-Register-Trigger标头，以分别注册基于图像的归因来源或归因触发器。应发送回哪个响应标头取决于触发注册的Attribution-Reporting-Eligible标头的值。

一旦浏览器收到包含图像文件的响应，相应的源或触发事件就会被触发。

注意：有关详细信息，请参阅归因报告 API。

您可以设置此属性的两个版本

• 布尔值，即仅使用attributionsrc名称。这表示您希望将Attribution-Reporting-Eligible标头发送到与src属性指向的服务器相同的服务器。当您在同一服务器上处理归因来源或触发器注册时，这很好用。注册归因触发器时，此属性是可选的，如果省略，将使用布尔值。
• 包含一个或多个 URL 的值，例如

html

<img
  src="image-file.png"
  alt="My image file description"
  attributionsrc="https://a.example/register-source
                     https://b.example/register-source" />

这在请求的资源不在您控制的服务器上或您只想在不同的服务器上处理归因来源注册的情况下非常有用。在这种情况下，您可以将一个或多个 URL 指定为attributionsrc的值。当资源请求发生时，Attribution-Reporting-Eligible标头将发送到attributionSrc中指定的一个或多个 URL 以及资源来源。然后，这些 URL 可以根据需要响应Attribution-Reporting-Register-Source或Attribution-Reporting-Register-Trigger标头以完成注册。

注意：指定多个 URL 意味着可以在同一功能上注册多个归因来源。例如，您可能有不同的广告系列需要衡量其成功率，这涉及到针对不同数据生成不同的报告。

crossorigin

指示是否必须使用CORS请求获取图像。从 CORS 请求返回的启用 CORS 的图像中的图像数据可以在<canvas>元素中重复使用，而无需标记为“受污染的”。

如果未指定crossorigin属性，则会发送非 CORS 请求（不带Origin请求标头），并且浏览器会将图像标记为受污染，并限制对其图像数据的访问，从而阻止其在<canvas>元素中使用。

如果指定了crossorigin属性，则会发送 CORS 请求（带有Origin请求标头）；但是，如果服务器没有选择通过来源站点允许跨源访问图像数据（不发送任何Access-Control-Allow-Origin响应标头，或者不在其发送的任何Access-Control-Allow-Origin响应标头中包含站点的来源），则浏览器会阻止图像加载，并在开发者工具控制台中记录 CORS 错误。

允许的值

anonymous

发送 CORS 请求时省略凭据（即没有cookie、X.509 证书或Authorization请求标头）。

use-credentials

发送 CORS 请求时包含任何凭据（即 cookie、X.509 证书和Authorization请求标头）。如果服务器没有选择与来源站点共享凭据（通过发送回Access-Control-Allow-Credentials: true响应标头），则浏览器会将图像标记为受污染，并限制对其图像数据的访问。

如果属性具有无效值，浏览器会将其视为使用了anonymous值。有关其他信息，请参阅CORS 设置属性。

decoding

此属性为浏览器提供了一个提示，指示它是否应在单个呈现步骤中执行图像解码以及呈现其他 DOM 内容，以使图像看起来更“正确”（sync），或者先呈现和显示其他 DOM 内容，然后解码图像并在稍后呈现（async）。实际上，async表示下一个绘制不会等待图像解码。

在静态<img>元素上使用decoding时，通常很难察觉到任何明显的差异。它们可能会最初呈现为空图像，而图像文件正在获取（从网络或缓存中获取），然后无论如何都会独立处理，因此内容更新的“同步”不太明显。但是，解码期间呈现的阻塞虽然通常很小，但可以衡量——即使用肉眼很难观察到。有关更详细的分析，请参阅图像解码属性到底做了什么？（tunetheweb.com，2023）。

当通过 JavaScript 将<img>元素动态插入 DOM 时，使用不同的decoding类型会导致更明显的差异——有关更多详细信息，请参阅HTMLImageElement.decoding。

允许的值

sync

与渲染其他 DOM 内容同步解码图像，并将所有内容一起呈现。

async

异步解码图像，在渲染和呈现其他 DOM 内容之后。

auto

对解码模式没有偏好；浏览器决定对用户最有利的模式。这是默认值。

elementtiming

标记图像以供PerformanceElementTimingAPI 观察。给定的值成为观察到的图像元素的标识符。另请参阅elementtiming属性页面。

fetchpriority

提供获取图像时应使用的相对优先级的提示。允许的值

high

相对于其他图像发出高优先级获取信号。

low

相对于其他图像发出低优先级获取信号。

auto

默认值：发出相对于其他图像自动确定获取优先级的信号。

height

图像的固有高度（以像素为单位）。必须是无单位的整数。

注意：包含height和width使浏览器能够在图像加载之前计算图像的纵横比。此纵横比用于预留显示图像所需的空間，减少甚至防止图像下载并绘制到屏幕上时发生布局偏移。减少布局偏移是良好的用户体验和网页性能的主要组成部分。

ismap

此布尔属性表示图像属于服务器端映射的一部分。如果是，则用户在图像上单击的坐标将发送到服务器。

注意：仅当<img>元素是具有有效href属性的<a>元素的后代时，才允许使用此属性。这为没有指向设备的用户提供了备用目标。

loading

指示浏览器应如何加载图像

eager

立即加载图像，而不管图像当前是否在可见视口中（这是默认值）。

lazy

延迟加载图像，直到它到达距视口一定计算距离，该距离由浏览器定义。目的是避免处理图像所需的网络和存储带宽，直到确定它很可能需要为止。这通常会在大多数典型用例中提高内容的性能。

注意：仅在启用 JavaScript 时才会延迟加载。这是一项反跟踪措施，因为如果用户代理在脚本禁用时支持延迟加载，则网站仍然可以通过在页面标记中策略性地放置图像来跟踪用户在整个会话中的大致滚动位置，以便服务器可以跟踪请求了多少图像以及何时请求。

注意：如果图像与可见元素的一部分没有交集，即使加载它们会改变这一点，设置了loading为lazy的图像也永远不会加载，因为未加载的图像的width和height为0。在延迟加载的图像上放置width和height可以解决此问题，并且是一种最佳实践，规范推荐这样做。这样做也有助于防止布局偏移。

referrerpolicy

一个字符串，指示在获取资源时使用哪个推荐来源。

• no-referrer：不会发送Referer标头。
• no-referrer-when-downgrade：不会将Referer标头发送到没有TLS（HTTPS）的来源。
• origin：发送的推荐来源将限制为推荐页面的来源：其方案、主机和端口。
• origin-when-cross-origin：发送到其他来源的推荐来源将限制为方案、主机和端口。相同来源的导航仍将包含路径。
• same-origin：将为相同来源发送推荐来源，但跨源请求将不包含推荐来源信息。
• strict-origin：仅在协议安全级别保持不变（HTTPS→HTTPS）时发送文档的来源作为推荐来源，但不要将其发送到安全性较低的目的地（HTTPS→HTTP）。
• strict-origin-when-cross-origin（默认值）：在执行相同来源请求时发送完整 URL，仅在协议安全级别保持不变（HTTPS→HTTPS）时发送来源，并将没有标头发送到安全性较低的目的地（HTTPS→HTTP）。
• unsafe-url：推荐来源将包含来源和路径（但不包含片段、密码或用户名）。此值不安全，因为它会将受 TLS 保护的资源的来源和路径泄漏到不安全的来源。

sizes

一个或多个以逗号分隔的字符串，指示一组源大小。每个源大小由以下组成：

1. 媒体条件。对于列表中的最后一项，必须省略此条件。
2. 源大小值。

媒体条件描述的是视口的属性，而不是图像的属性。例如，(max-height: 500px) 1000px建议如果视口的高度不超过 500px，则使用 1000px 宽度的源。

源大小值指定图像的预期显示大小。用户代理使用当前源大小从srcset属性提供的源中选择一个源，当这些源使用宽度（w）描述符进行描述时。所选源大小会影响图像的固有大小（如果未应用任何CSS样式，则图像的显示大小）。如果srcset属性不存在或不包含任何具有宽度描述符的值，则sizes属性无效。

src

图像URL。对于<img>元素是必需的。在支持srcset的浏览器中，src被视为具有像素密度描述符1x的候选图像，除非srcset中已定义具有此像素密度描述符的图像，或者除非srcset包含w描述符。

srcset

一个或多个以逗号分隔的字符串，指示用户代理可能使用的图像源。每个字符串由以下组成：

1. 图像的URL
2. 可选地，后面跟有一个空格，然后是以下之一：
   • 宽度描述符（正整数后跟w）。宽度描述符除以sizes属性中给定的源大小以计算有效像素密度。
   • 像素密度描述符（正浮点数后跟x）。

如果未指定描述符，则源将分配默认描述符1x。

在同一个srcset属性中混合宽度描述符和像素密度描述符是不正确的。重复描述符（例如，同一个srcset中的两个源都用2x描述）也是无效的。

如果srcset属性使用宽度描述符，则还必须存在sizes属性，否则srcset本身将被忽略。

用户代理可自行决定选择任何可用的源。这为他们提供了很大的自由度来根据用户偏好或带宽条件定制其选择。有关示例，请参阅我们的响应式图像教程。

width

图像的固有宽度（以像素为单位）。必须是无单位的整数。

usemap

与元素关联的图像映射的部分URL（以#开头）。

注意：如果<img>元素位于<a>或<button>元素内部，则不能使用此属性。

align 已弃用

将图像与其周围环境对齐。请使用float和/或vertical-alignCSS属性来代替此属性。允许的值

top

等效于vertical-align: top或vertical-align: text-top

middle

等效于vertical-align: -moz-middle-with-baseline

bottom

默认值，等效于vertical-align: unset或vertical-align: initial

left

等效于float: left

right

等效于float: right

border 已弃用

图像周围边框的宽度。请使用borderCSS属性来代替。

hspace 已弃用

图像左右两侧空白区域的像素数。请使用marginCSS 属性来代替。

longdesc 已弃用

指向图像更详细描述的链接。可能的值为URL或元素id。

注意：此属性在最新的W3C版本HTML 5.2中提到，但已从WHATWG的HTML 活跃标准中删除。它的未来尚不确定；作者应使用WAI-ARIA替代方案，例如aria-describedby或aria-details。

name 已弃用

元素的名称。请使用id属性来代替。

vspace 已弃用

图像上下两侧空白区域的像素数。请使用marginCSS 属性来代替。

<img>是一个替换元素；默认情况下，它的display值为inline，但其默认尺寸由嵌入图像的内在值定义，就像它是inline-block一样。您可以设置诸如border/border-radius、padding/margin、width、height等属性在图像上。

<img>没有基线，因此当图像在内联格式化上下文中与vertical-align: baseline一起使用时，图像的底部将放置在文本基线上。

您可以使用object-position属性在元素的框内定位图像，并使用object-fit属性调整图像在框内的尺寸（例如，图像是否应该适合框或即使需要裁剪也填充框）。

根据图像的类型，它可能具有内在宽度和高度。但是，对于某些图像类型，内在尺寸是不必要的。例如，如果SVG图像的根<svg>元素没有设置width或height，则它没有内在尺寸。

alt属性的值应为图像内容提供清晰简洁的文本替换。它不应描述图像本身的存在或图像的文件名。如果alt属性被故意省略，因为图像没有文本等效项，请考虑使用其他方法来呈现图像试图传达的内容。

不要

<img alt="image" src="penguin.jpg" />

做

<img alt="A Rockhopper Penguin is standing on a beach." src="penguin.jpg" />

当图像上没有alt属性时，一些屏幕阅读器可能会宣布图像的文件名。如果文件名不能代表图像的内容，这可能会导致令人困惑的体验。

• 替代文本决策树 • 图像 • WAI Web 可访问性教程
• 替代文本：终极指南 — Axess Lab
• 如何设计优秀的替代文本：简介 | Deque
• MDN 理解 WCAG，指南 1.1 说明
• 理解成功标准 1.1.1 | W3C 理解 WCAG 2.0

由于VoiceOver 错误，VoiceOver 无法正确地将 SVG 图像宣布为图像。将role="img"包含到所有具有 SVG 源文件的<img>元素中，以确保辅助技术正确地将 SVG 宣布为图像内容。

<img src="mdn.svg" alt="MDN" role="img" />

title属性不是alt属性的可接受替代品。此外，避免在同一图像上声明的title属性中复制alt属性的值。这样做可能会导致某些屏幕阅读器两次宣布相同的文本，从而造成混乱的体验。

title属性也不应被用作补充字幕信息来伴随图像的alt描述。如果图像需要标题，请使用figure和figcaption元素。

title属性的值通常以工具提示的形式呈现给用户，该工具提示在光标停止在图像上移动后不久出现。虽然这可以为用户提供其他信息，但你不应该假设用户会看到它：用户可能只有键盘或触摸屏。如果您有对用户特别重要或有价值的信息，请使用上述方法之一内联显示，而不是使用title。

• 使用 HTML title 属性 – 更新 | Paciello Group

以下示例将图像嵌入到页面中，并包含用于辅助功能的替代文本。

<img src="favicon144.png" alt="MDN" />

此示例建立在上一个示例的基础上，展示了如何将图像转换为链接。为此，将<img>标签嵌套在<a>中。您应该使替代文本描述链接指向的资源，就像使用文本链接一样。

<a href="https://mdn.org.cn">
  <img src="favicon144.png" alt="Visit the MDN site" />
</a>

在此示例中，我们包含一个srcset属性，其中包含对徽标的高分辨率版本的引用；这将在高分辨率设备上加载，而不是src图像。在支持srcset的用户代理中，src属性中引用的图像被计为1x候选。

<img src="favicon72.png" alt="MDN" srcset="favicon144.png 2x" />

当包含w描述符时，在支持srcset的用户代理中，src属性将被忽略。当(max-width: 600px)媒体条件匹配时，将加载宽度为 200 像素的图像（它是与200px最接近匹配的图像），否则将加载另一个图像。

<img
  src="clock-demo-200px.png"
  alt="The time is 12:45."
  srcset="clock-demo-200px.png 200w, clock-demo-400px.png 400w"
  sizes="(max-width: 600px) 200px, 50vw" />

尽管<img>元素具有无害的用途，但它们可能会对用户安全和隐私造成不良后果。有关更多信息和缓解措施，请参阅Referer 标头：隐私和安全问题。

• <picture>、<object>和<embed>元素
• object-fit、object-position、image-orientation、image-rendering和image-resolution：与图像相关的 CSS 属性。
• HTMLImageElement此元素的接口
• HTML 中的图像
• 图像文件类型和格式指南
• 响应式图像