<img>:图像嵌入元素

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

<img> HTML 元素将一张图像嵌入文档。

尝试一下

上面的例子展示了 <img> 元素的用法:

  • src 属性是必须的,它包含了你想嵌入的图片的路径。
  • alt 属性包含一条对图像的文本描述,这不是强制性的,但对无障碍而言,它难以置信地有用——屏幕阅读器会将这些描述读给需要使用阅读器的使用者听,让他们知道图像的含义。如果由于某种原因无法加载图像,普通浏览器也会在页面上显示 alt 属性中的备用文本:例如,网络错误、内容被屏蔽或链接过期。

还有很多其他属性,可以实现各种不同的目的:

支持的图像格式

HTML 标准并没有给出需要支持的图像格式的列表,因此每个用户代理支持一组不同的格式。

备注: 网页浏览器图像格式指南提供了有关图像格式及 Web 浏览器支持的综合信息。本节只是一个总结!

Web 最常用的图像格式是:

推荐使用诸如 WebPAVIF 等图像格式,因为它们在静态图像和动画的性能均比 PNG、JPEG、JIF 好得多。WebP 得到了广泛的支持,而 AVIF 则缺乏 Safari 的支持。

对于必须以不同尺寸准确绘制的图像,则仍然推荐使用 SVG 格式。

图像加载错误

如果在加载或渲染图像时发生错误,且设置了至少一个 onerror 事件处理器来处理 error 事件,那么设置的事件处理器就会被调用。这样的错误可能发生在各种不同的情况下,包括:

  • src 属性的属性值为空("")或者 null
  • src 属性的 URL 和用户正在浏览的页面的 URL 完全相同。
  • 图像出于某些原因损坏了,从而无法加载。
  • 图像的元数据被破坏了,无法检索它的分辨率/宽高,而且在 <img> 元素的属性中没有指定宽度/高度。
  • 用户代理尚未支持该图片所用的格式。

属性

此元素支持全局属性

alt

定义了图像的备用文本描述。

备注: 浏览器并非总是会显示图像。比如:

  • 非可视化浏览器(Non-visual browsers)(比如有视力障碍的人使用的音频浏览器)
  • 用户选择不显示图像(比如为了节省带宽,或出于隐私考虑)
  • 图像文件无效,或是使用了不支持的格式

在这些情况下,浏览器很可能会将图像替换为图像所属 <img> 元素的 alt 属性所提供的文本。基于上面罗列的原因,建议尽可能地通过 alt 属性提供一些有用的信息。

如果把这个属性设置为空字符串(alt=""),则表明该图像不是内容的关键部分(这是一种装饰或者一个追踪像素点),非可视化浏览器在渲染的时候可能会忽略它。而且,如果图片加载失败,可视化浏览器会隐藏表示图片损坏的图标。

将图像复制并粘贴为文本,或是将图像的链接保存为浏览器书签时,也会用到此属性。

crossorigin

这个枚举属性表明是否必须使用 CORS 完成相关图像的抓取。启用 CORS 的图像可以在 <canvas> 元素中重复使用,而不会被标记为“污染(tainted)”。

如果未指定 crossorigin 属性,则会发送不启用 CORS 的请求(不会携带 Origin 请求标头),且浏览器会将图像标记为“被污染”并拒绝对图像数据的访问,阻止其在 <canvas> 元素中的使用。

如果指定crossorigin 属性,则会发送启用 CORS 的请求(会携带 Origin 请求标头);但是如果服务器不选择允许源站点对图像数据进行跨源访问(不发送任何 Access-Control-Allow-Origin 响应标头,或发送的 Access-Control-Allow-Origin 标头中不包含源站点),浏览器则会阻止图像的加载,并在开发者工具的控制台中记录 CORS 错误。

允许的值有:

anonymous

发送忽略凭据的跨源请求(即,不携带 cookieX.509 证书Authorization 请求标头)。

use-credentials

发送携带凭据的跨源请求(比如 cookie、X.509 证书和 Authorization 请求标头)。如果服务器不选择与源站共享凭据(通过返回 Access-Control-Allow-Credentials: true 响应标头) ,则浏览器会将图像标记为被污染且限制对其图像数据的访问。

如果属性是无效值,浏览器默认将其当做 anonymous 关键字。更多信息,请查看 CORS 属性设置

decoding

为浏览器提供图像解码方式上的提示。允许的值:

sync

同步解码图像,实现与其他内容互斥的原子渲染。

async

异步解码图像,以减少其他内容的渲染延迟。

auto

默认值:不指定解码方式,由浏览器决定哪一种对用户来说是最合适的。

fetchpriority 实验性

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

high

表示其获取优先级相对其他图像要高。

low

表示其获取优先级相对其他图像要低。

auto

默认值:表示自动确定其相对其他图像的获取优先级。

height

图像的固有高度,以像素为单位。必须是没有单位的整数值。

备注: 同时包括 heightwidth 使浏览器在加载图像之前计算图像的长宽比。此长宽比用于保留显示图像所需的空间,减少甚至防止在下载图像并将其绘制到屏幕上时布局的偏移。减少布局偏移是良好用户体验和 Web 性能的主要组成部分。

ismap

这个布尔属性表示图像是否是服务器端图像映射的一部分。如果是,那么点击图片的精准坐标将会被发送到服务器。

备注: 只有在 <img> 元素是一个拥有有效 href 属性的 <a> 元素的后代元素的情况下,这个属性才会被允许使用。

loading

指示浏览器应当如何加载该图像。允许的值:

eager

立即加载图像,不管它是否在可视视口(visible viewport)之外(默认值)。

lazy

延迟加载图像,直到它和视口接近到一个计算得到的距离(由浏览器定义)。目的是在需要图像之前,避免加载图像所需要的网络和存储带宽。这通常会提高大多数典型用场景中内容的性能。

备注: 仅在启用 JavaScript 时才会延迟加载。这是一种反跟踪的措施,因为,如果用户代理在禁用脚本的情况下支持延迟加载,网站可以在会话中策略性地放置图像,通过服务器跟踪请求了多少图像以及请求在何时发起,来跟踪用户在整个会话期间的大致滚动位置。

referrerpolicy

一个字符串,指示在获取资源时使用的来源地址(referrer):

  • no-referrer:不会发送 Referer 标头。
  • no-referrer-when-downgrade:若未使用 TLSHTTPS)导航到源站,则不发送 Referer 标头。
  • origin:发送到源站的来源地址将被限制为:协议主机端口
  • origin-when-cross-origin:发送到其他来源的来源地址会被限制为协议、主机和端口。同源导航仍将包含路径。
  • same-origin:仅同源请求发送来源地址,而跨源请求则不包含来源地址信息。
  • strict-origin:仅在协议安全级别保持不变(HTTPS→HTTPS)的情况下将文档的来源作为来源地址发送。而在目标的安全性降低(HTTPS→HTTP)时则不发送来源地址。
  • strict-origin-when-cross-origin(默认值):执行同源请求时发送完整的 URL,且仅在协议安全级别保持不变(HTTPS→HTTPS)时发送来源(origin),在目标安全性降低(HTTPS→HTTP)时则不发送来源。
  • unsafe-url:来源地址包括来源(origin)路径(path)(但不包括片段密码用户名)。这个值是不安全的,因为它将来源和路径从受 TLS 保护的资源泄露到不安全的来源。
sizes

表示资源大小的、以逗号隔开的一个或多个字符串。每一个资源大小包括:

  1. 一个媒体条件。最后一项一定是被忽略的。
  2. 一个资源大小的值。

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

资源尺寸的值被用来指定图像的预期尺寸。当 srcset 中的资源使用了宽度描述符 w 时,用户代理会使用当前图像大小来选择 srcset 中合适的一个图像 URL。被选中的尺寸影响图像的显示大小(如果没有影响大小的 CSS 样式被应用的话)。如果没有设置 srcset 属性,或者没有属性值,那么 sizes 属性也将不起作用。

src

图像的 URL,这个属性对 <img> 元素来说是必需的。在支持 srcset浏览器中,src 被当做拥有一个像素密度的描述符 1x 的候选图像处理,除非一个图像拥有这个像素密度描述符已经被在 srcset 或者 srcset 包含 w 描述符中定义了。

srcset

以逗号分隔的一个或多个字符串列表表明一系列用户代理使用的可能的图像。每一个字符串由以下组成:

  1. 指向图像的 URL

  2. 可选地,再加一个空格之后,附加以下的其一:

    • 一个宽度描述符(一个正整数,后面紧跟 w 符号)。该整数宽度除以 sizes 属性给出的资源(source)大小来计算得到有效的像素密度,即换算成和 x 描述符等价的值。
    • 一个像素密度描述符(一个正浮点数,后面紧跟 x 符号)。

如果没有指定源描述符,那它会被指定为默认的 1x

在相同的 srcset 属性中混合使用宽度描述符和像素密度描述符时,会导致该值无效。重复的描述符(比如,两个源在相同的 srcset 两个源都是 2x)也是无效的。

用户代理自行决定选择任何可用的来源。这位它们提供了一个很大的选择余地,可以根据用户偏好或带宽条件等因素来进行选择。有关示例,可以参阅响应式图像教程。

width

图像的宽度,以像素为单位。必须是没有单位的整数。

usemap

与元素相关联的图像映射(image map)的部分 URL(以 # 开始的部分)。

备注: 如果 <img> 元素是 <a><button> 元素的后代元素则不能使用这个属性。

已废弃的属性

align 已弃用

图像相对于它周围上下文的对齐。使用 float 和/或 vertical-align 这两个 CSS 属性作为代替。允许的值:

top

等价于 vertical-align: topvertical-align: text-top

middle

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

bottom

默认值,等价于 vertical-align: unsetvertical-align: initial

left

等价于 float: left

等价于 float: right

border 已弃用

图像周围的边框宽度。使用 CSS 属性 border 代替此废弃属性。

hspace 已弃用

插入到图像的左侧和右侧的空白像素的值。使用 CSS 属性 margin 代替此废弃属性。

longdesc 已弃用

一个指向更详细的图像描述的链接。可能的值是一个 URL 或一个页面上其他元素的 id

备注: 此属性在当前最新的 W3C 版本——HTML 5.2 中被提到,但在 WHATWG 组织的 HTML Living Standard 中依然处于被移除的状态。它的未来尚无定数;开发者应使用 WAI-ARIA 这一代替方法,例如:aria-describedbyaria-details

name 已弃用

元素的名字。使用 id 属性代替此废弃属性。

vspace 已弃用

插入到图像的上方和下方的空白像素的数组。使用 CSS 属性 margin 代替此废弃属性。

使用 CSS 添加样式

<img> 是一个可替换元素。它的 display 属性的默认值是 inline,但是它的默认分辨率是由被嵌入的图片的原始宽高来确定的,使得它就像 inline-block 一样。你可以为 <img> 设置 border/border-radiuspadding/marginwidthheight 等 CSS 属性。

<img> 没有基线(baseline),这意味着,当在一个内联格式化上下文(inline formatting context)中使用 vertical-align: baseline 时,图像的底部将会与容器的文字基线对齐。

你可以使用 object-position 属性将图形定位在元素的框内,并使用 object-fit 属性调整框内图像的大小(例如,如果图像需要裁剪,则其是否需要调整以符合框的大小,或填满整个框)。

根据图像的类型,其可能会有一个原始的宽和高(原始分辨率)。对于一些类型的图像,原始分辨率并不是必要的。比如说,SVG 图像,如果它们的根 <svg> 元素没有 widthheight 属性,SVG 图像就可以没有原始分辨率。

示例

备用文字

下面的示例将图像嵌入到页面中,且包含用于改善无障碍的备用文本。

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

图像链接

此示例建立在前一个示例的基础上,展示了如何将图像转换为链接。为做到这一点,将 <img> 标签嵌套在 <a> 之内。这时,备用文本应当描述链接所指向的资源,就像是文本链接一样。

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

使用 srcset 属性

在这个例子中,我们包含了一个 srcset 属性,它引用了 MDN 标志高清版本;在高分辨率设备上,它将被优先加载,取代 src 属性中的图像。在支持 srcset用户代理中,src 属性中的图片被作为 1x 候选项。

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

使用 srcset 和 sizes 属性

在支持 srcset 的用户代理中,当使用 w 描述符时,src 属性会被忽略。当匹配了媒体条件 (max-width: 600px) 时,将加载 200 像素宽的图像(最匹配的图像),否则将加载另一幅图像。

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

备注: 若要看到大小调整的效果,请打开单独的页面查看示例,以便拖动窗口,调整内容区域的大小。

安全与隐私方面的考量

虽然 <img> 元素的用途是很单纯(innocent)的,但是它们可对用户安全和隐私造成不良的后果。参见 Referer 标头:隐私与安全性考量以获取更多信息和缓解措施。

无障碍考量

使用有实际意义的备用描述

alt 属性的值应该清晰、简洁地描述图像的内容。它不应该描述“图像的存在”,或仅仅包含图像的文件名。如果因为图像没有等价的文本描述,alt 属性只得不写或留白,那么可以考虑使用其他方法来呈现图像试图传递的内容。

不要

html
<img alt="图片" src="penguin.jpg" />

而是

html
<img alt="一只站在沙滩上的跳岩企鹅。" src="penguin.jpg" />

当图像上没有 alt 属性时,一些屏幕阅读器可能会读出图像的文件名。如果文件名不能代表图像的内容,甚至是一团乱码,这可只能造成令人迷惑的体验。

将 SVG 识别为图像

由于 VoiceOver bug,VoiceOver 无法正确地将 SVG 图像渲染为图像。在所有使用 SVG 资源文件的 <img> 元素中包含 role="img" 以保证无障碍技术正确地将 SVG 声明为图像内容。

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

title 属性

title 属性不是 alt 属性可接受的替代品。并且,避免将 alt 属性的值直接复制到同一幅图片的title 属性上。这样可能会让一些屏幕阅读器把同一段描述读两遍,造成一定程度上的困扰。

title 属性也不该被用作一幅图片在 alt 之外的补充说明信息。如果一幅图片需要小标题,使用 figurefigcaption 元素。

title 元素的值一般作为提示条(tooltip)呈现给用户,在光标于图片上停下后显示出来。尽管这确实能给用户提供更多的信息,你不该假定用户真的能看到:用户可能只有键盘或触摸屏。如果要把特别重要的信息提供给用户,选择上面提供的一种方法将其内联显示,而不是使用 title

技术总结

内容类别 流式内容短语内容嵌入内容可感知内容。如果元素有 usemap 属性,则其也是交互式内容的一种。
允许的内容 无;其为 空元素
标签省略 必须有开始标签,且不能有结束标签。
允许的父元素 接受嵌入内容的任何元素。
隐式 ARIA 角色
  • 具有非空 alt 属性或没有 alt 属性:img
  • 具有空 alt 属性:presentation
允许的 ARIA 角色
DOM 接口 HTMLImageElement

规范

Specification
HTML
# the-img-element

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
img
align
Deprecated
alt
Aspect ratio computed from width and height attributes
attributionsrc
Experimental
border
Deprecated
crossorigin
decoding
fetchpriority
height
hspace
Deprecated
ismap
loading
longdesc
Deprecated
name
Deprecated
referrerpolicy
no-referrer-when-downgrade
origin-when-cross-origin
unsafe-url
sizes
auto value
src
srcset
usemap
Content is case-sensitive
vspace
Deprecated
width

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Deprecated. Not for use in new websites.
See implementation notes.
Uses a non-standard name.
Has more compatibility info.

参见