<img>：图片嵌入元素

试一试

<img
  class="fit-picture"
  src="/shared-assets/images/examples/grapefruit-slice.jpg"
  alt="Grapefruit slice atop a pile of other slices" />

.fit-picture {
  width: 250px;
}

上述示例展示了 <img> 元素的用法

• src 属性包含要嵌入图像的路径。如果 srcset 属性可用，则它不是强制性的。但是，必须提供 src 或 srcset 属性中的至少一个。
• 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 或 srcset 属性为空 ("") 或 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

async

auto

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

elementtiming

标记图像以便由 PerformanceElementTiming API 观察。给定值成为被观察图像元素的标识符。另请参阅 elementtiming 属性页面。

fetchpriority

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

high

相对于其他图像，以高优先级获取图像。

low

相对于其他图像，以低优先级获取图像。

auto

不对获取优先级设置偏好。这是默认值。如果未设置值或设置了无效值，则使用此值。

有关更多信息，请参阅 HTMLImageElement.fetchPriority。

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：将不向没有 TLS (HTTPS) 的源发送 Referer 头。
• 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

一个或多个用逗号分隔的值，可以是源大小或 auto 关键字。

源大小由以下部分组成

1. 一个媒体条件，列表中最后一项可省略。
2. 一个源大小值。

媒体条件描述的是视口的属性，而不是图像的属性。例如，(height <= 500px) 1000px 建议如果视口高度为 500px 或更小，则使用 1000px 宽的图像源。因为源大小描述符指定了布局时图像要使用的宽度，所以媒体条件通常（但不一定）基于宽度。

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

源大小值可以是任何非负的长度。它不能使用除数学函数之外的 CSS 函数。单位的解释方式与媒体查询相同，这意味着所有相对长度单位都相对于文档根而不是 <img> 元素。例如，em 值相对于根字体大小，而不是图像的字体大小。百分比值不允许。

auto 关键字可以替换整个大小列表或列表中的第一个条目。它仅在与 loading="lazy" 结合使用时有效，并解析为图像的具体大小。由于图像的固有大小尚不清楚，因此还应指定 width 和 height 属性（或等效的 CSS），以防止浏览器假定图像的默认宽度为 300px。为了更好地向不支持 auto 的浏览器进行向后兼容，您可以在 sizes 属性中的 auto 之后包含备用大小

html

<img
  loading="lazy"
  width="200"
  height="200"
  sizes="auto, (max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
  srcset="
    swing-200.jpg   200w,
    swing-400.jpg   400w,
    swing-800.jpg   800w,
    swing-1600.jpg 1600w
  "
  src="swing-400.jpg"
  alt="Kettlebell Swing" />

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-align CSS 属性。允许的值

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 已弃用

图像周围边框的宽度。请改用 border CSS 属性。

hspace 已废弃

图像左右两侧的空白像素数。请改用 margin CSS 属性。

longdesc 已废弃

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

注意：此属性在 HTML 规范中被视为已过时。它未来不确定；作者应使用 WAI-ARIA 替代方案，例如 aria-describedby 或 aria-details。

name 已废弃

元素的名称。请改用 id 属性。

vspace 已废弃

图像上方和下方的空白像素数。请改用 margin CSS 属性。

使用 CSS 样式

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

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

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

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

无障碍

编写有意义的替代描述

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

不要

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

要

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

一项重要的可访问性测试是，将 alt 属性内容与前面的文本内容一起阅读，以查看它是否传达与图像相同的含义。例如，如果图像前面是句子“在我的旅行中，我看到了一只可爱的小动物：”，屏幕阅读器可能会将“不要”示例读作“在我的旅行中，我看到了一只可爱的小动物：图像”，这没有意义。“要”示例可能会被屏幕阅读器读作“在我的旅行中，我看到了一只可爱的小动物：海滩上的一只企鹅。”，这就有意义了。

对于用于触发动作的图像，例如嵌套在 <a> 或 <button> 元素内的图像，请考虑在 alt 属性值中描述触发的动作。例如，您可以写 alt="下一页" 而不是 alt="右箭头"。您还可以考虑在 title 属性中添加可选的进一步描述；如果用户请求，屏幕阅读器可能会读取它。

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

• Alt 决策树 • 图像 • WAI 网络可访问性教程
• Alt 文本：终极指南 — Axess Lab
• 如何设计出色的 Alt 文本：简介 | Deque
• MDN 理解 WCAG，指南 1.1 解释
• 理解成功标准 1.1.1 | W3C 理解 WCAG 2.0

将 SVG 标识为图像

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

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

title 属性

title 属性不能替代 alt 属性。此外，请避免在同一图像上声明的 title 属性中重复 alt 属性的值。这样做可能会导致某些屏幕阅读器重复宣布相同的文本，从而造成令人困惑的体验。

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

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

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

示例

替代文本

以下示例将图像嵌入页面，并包含用于可访问性的替代文本。

<img src="/shared-assets/images/examples/favicon144.png" alt="MDN" />

图像链接

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

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

使用 srcset 属性

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

<img
  src="/shared-assets/images/examples/favicon72.png"
  alt="MDN"
  srcset="/shared-assets/images/examples/favicon144.png 2x" />

使用 srcset 和 sizes 属性

当包含 w 描述符时，支持 srcset 的用户代理会忽略 src 属性。当 (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="(width <= 600px) 200px, 50vw" />

安全和隐私问题

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

技术摘要

规范

浏览器兼容性

另见

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