figure 和 figcaption 的核心价值是为独立内容单元提供清晰、可访问、语义准确的说明；关键在精准分工与结构合规，figcaption 必须是 figure 的首个或末个直接子元素，不可嵌套于 div 等元素内，且需避免复述内容本身，而应说明用途、场景或设计意图。

和

的核心价值，是让代码块或图片这类**独立内容单元**拥有清晰、可访问、语义准确的说明。关键不在“加文字”，而在“精准分工”和“结构合规”。

figcaption 必须直接归属 figure，且只出现一次
它只能是

的第一个或最后一个直接子元素，中间不能插 div、p 或按钮。屏幕阅读器按 DOM 顺序播报：先读 figcaption（带上下文），再读内容（如代码或图片）。结构错，语义就断。
✅ 正确：

<figure>
  <figcaption>清单 4：用户登录态校验的 JWT 解析逻辑（Node.js）</figcaption>
  <pre class="brush:php;toolbar:false;"><code>const payload = jwt.verify(token, SECRET);</code>

❌ 错误：

<figure>
  <div><figcaption>……</figcaption></div>
  <pre class="brush:php;toolbar:false;">...

标题说明要回答“为什么放这里”，不是重复 alt 或代码本身

• 的 alt 属性不存在，但 <pre class="brush:php;toolbar:false;">&lt;code&gt; 内容本身是可视文本，所以 figcaption 不该复述代码行；它应点明用途、场景、版本或设计意图。 &lt;/li&gt;&lt;li&gt;图片的 alt 描述“图里有什么”，figcaption 解释“这张图为什么在这”。两者互补，不可互换。 &lt;/li&gt;&lt;/ul&gt;&lt;p&gt;常见有效写法包括： &lt;/p&gt;&lt;div class=&quot;aritcle_card flexRow&quot;&gt; &lt;div class=&quot;artcardd flexRow&quot;&gt; &lt;a class=&quot;aritcle_card_img&quot; href=&quot;/xiazai/skill10828&quot; title=&quot;财经HTML高端海报生成&quot;&gt;&lt;img src=&quot;https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg&quot; alt=&quot;财经HTML高端海报生成&quot; &gt;&lt;/a&gt; &lt;div class=&quot;aritcle_card_info flexColumn&quot;&gt; &lt;a href=&quot;/xiazai/skill10828&quot; title=&quot;财经HTML高端海报生成&quot;&gt;财经HTML高端海报生成&lt;/a&gt; &lt;p&gt;复杂得财经如何变成清晰，适合手机看的海报？如何加上你的IP&lt;/p&gt; &lt;/div&gt; &lt;a href=&quot;/xiazai/skill10828&quot; title=&quot;财经HTML高端海报生成&quot; class=&quot;aritcle_card_btn flexRow flexcenter&quot;&gt;&lt;b&gt;&lt;/b&gt;&lt;span&gt;下载&lt;/span&gt; &lt;/a&gt; &lt;/div&gt; &lt;/div&gt;&lt;ul&gt;&lt;li&gt;带编号与归类：&lt;code&gt;&lt;figcaption&gt;图3-2：iOS 端表单提交异常捕获堆栈（v2.4.1）&lt;/figcaption&gt;&lt;/code&gt; &lt;/li&gt;&lt;li&gt;指向结论或关联：&lt;code&gt;&lt;figcaption&gt;该算法在 10 万级数据下平均耗时降低 37%，见性能对比表&lt;/figcaption&gt;&lt;/code&gt; &lt;/li&gt;&lt;li&gt;标注来源与限制：&lt;code&gt;&lt;figcaption&gt;SVG 架构图（基于 Figma 导出，不含交互状态）&lt;/figcaption&gt;&lt;/code&gt; &lt;/li&gt;&lt;li&gt;区分变体说明：&lt;code&gt;&lt;figcaption&gt;响应式断点配置（mobile-first，最小支持 320px 宽度）&lt;/figcaption&gt;&lt;/code&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;&lt;strong&gt;复杂代码块建议搭配 &lt;pre class=&quot;brush:php;toolbar:false;&quot;&gt; + &lt;code&gt; + lang 属性&lt;/strong&gt;&lt;br /&gt; figcaption 不负责语法高亮或语言识别，这部分由 &lt;code lang=&quot;js&quot;&gt; 或 &lt;code class=&quot;python&quot;&gt; 承担。figcaption 只管宏观定位： &lt;/p&gt;&lt;ul&gt;&lt;li&gt;是示例？是生产代码片段？是已废弃逻辑？ &lt;/li&gt;&lt;li&gt;属于哪个模块？对应哪条需求？是否含副作用？&lt;br /&gt; 例如： &lt;pre class='brush:html;toolbar:false;'&gt;&lt;figure&gt; &lt;figcaption&gt;模块入口：useAuthStore.ts 中的 token 刷新防重逻辑（防并发请求）&lt;/figcaption&gt; &lt;pre class=&quot;brush:php;toolbar:false;&quot;&gt;&lt;code class=&quot;typescript&quot;&gt;export const refreshAccessToken = async () =&gt; { ... }&lt;/code&gt;</pre>

多段相关代码不要塞进一个 figure
若展示“请求发起 → 响应处理 → 错误兜底”三步，应拆为三个独立

，各自配专属 figcaption。统一说明可放在外层

或

下，避免一个标题覆盖多个语义单元。

图与代码共用同一套规则：只有能单独引用、删掉不影响正文主干、可移入附录仍成立的内容，才值得用

+

。装饰性截图、内联小图标、轮播帧、banner 图都不在此列。

立即学习“前端免费学习笔记（深入）”；