如何用 figure 和 figcaption 正确标注图片与代码

用 <figure> + <figcaption> 是 HTML5 里标注图片和代码块的标准做法：<figure> 是"自包含内容"的语义容器，<figcaption> 是它唯一的说明文字，必须是 <figure> 的第一个或最后一个子元素；图片的 alt 仍然必须写，figcaption 不能替代它。

figure 和 figcaption 分别是什么？

结论：<figure> 表示一段可以从正文中整体抽走、单独搬走也不影响语义的内容，<figcaption> 是它的标题／说明。

按 HTML5 规范（W3C HTML Living Standard），<figure> 属于 sectioning root，内容可以是图片、代码块、图表、表格、引用、音视频。<figcaption> 最多出现一个，位置只能是第一个或最后一个子元素——放中间是无效标记。<figcaption> 是可选的，但一旦要给图注，就只能用它。

浏览器支持：Chrome 8+、Firefox 4+、Safari 5.1+、IE9+ 均支持；IE8 及更早版本需要引入 html5shiv 才能正常渲染。

图片标注怎么写才正确？

结论：<img> 负责"这张图是什么"（alt），<figcaption> 负责"这张图在本文里说明什么"，两者不要写重复内容。

<figure>
  <img src="dashboard-2024-q3.png"
       alt="2024 年第三季度后台看板，折线图显示日活从 8 万增长到 12 万"
       width="960" height="540" loading="lazy">
  <figcaption>图 1：2024 Q3 日活趋势（数据来源：后台统计，2024-10-01 导出）</figcaption>
</figure>

注意事项有三条：一是 alt 描述图像内容本身，figcaption 补充编号、来源、时间、解读，二者互补而非复制；二是写上 width / height 或给 CSS 加 img { max-width: 100%; height: auto; }，否则宽图在手机上会撑破容器；三是读屏器会把 <figure> 暴露为 figure 角色、把 figcaption 作为该区块的说明朗读，但不同辅助技术的处理并不完全一致，所以关键信息不要只放在 figcaption 里。

代码块怎么用 figure 标注文件名和语言？

结论：用 <figure> 包 <pre><code>，<figcaption> 放文件名或代码用途，语法高亮交给 class="language-xxx"。

<figure>
  <figcaption>src/utils/date.ts</figcaption>
  <pre><code class="language-ts">export function toISO(d: Date): string {
  return d.toISOString().slice(0, 10);
}</code></pre>
</figure>

要点：<figcaption> 放在 <pre> 之前，读起来就是"这是哪个文件的代码"；HTML 里写代码必须转义 <、>、&，否则标签会被解析；代码必须是真实文本，不要用截图代替——图片里的代码无法被搜索、复制和读屏。

什么时候不该用 figure？

结论：装饰性图片、正文中随手插的小图标、必须依赖上下文才有意义的片段，都不该用 <figure>。

判断标准只有一句：把它整块搬到别的文章里，还成立吗？成立就用 figure；不成立就用普通 <img> 或 CSS background-image。同理，纯装饰图应使用空 alt=""，让读屏器直接跳过。

figcaption 怎么自动编号？

结论：figcaption 本身不会自动生成"图 1"，需要靠 CSS counter 实现。

article { counter-reset: fig; }
figcaption { counter-increment: fig; margin-top: .5rem;
  font-size: .875rem; color: #666; }
figcaption::before { content: "图 " counter(fig) "："; }
figure { margin: 0 0 1.5rem; }   /* 浏览器默认 margin 是 1em 40px，建议重置 */

最后一段收束：记四条就够——<figure> 装可独立存在的内容，<figcaption> 只能是首子或尾子且最多一个，图片的 alt 与图注分工不重复，代码块用 <pre><code> 而不是截图。