HTML 格式化

HTML 格式化的职责非常明确：把一段被挤成一行的、从 CMS 抠出来的或从模板编译产物里拷出来的 HTML，重新缩进成“一眼能看出树形结构”的样子。它不会增删元素、不会改属性、不会影响浏览器的渲染结果，只会改变这份 HTML 在屏幕上呈现给人看的形状。换句话说，格式化前后是同一棵 DOM 树，只是这棵树是否容易被人扫描。

为什么真实世界里的 HTML 通常不带缩进

线上 HTML 通常来自模板编译、CMS 渲染或浏览器导出，构建管线会顺手把元素之间的空白吃掉，因为浏览器并不依赖这些空白来决定布局。可一旦你需要打开它来排查样式问题、做无障碍审查、抽离组件，原本的“结构感”就完全消失了，要靠脑子重新拼一遍。格式化器把这件事自动化，让结构在打开文件的瞬间就回到屏幕上。

格式化会改什么、必须保留什么

格式化器只动“元素之间”的排版：标签前后的空白、整体缩进层级、属性的对齐方式。它不能改变 DOM 树形、不能改属性名/属性值、不能改文本内容和注释，也绝不能动 `<pre>`、`<textarea>`、`<script>`、`<style>` 内部——这些位置的空白是有语义的，是页面渲染或脚本行为的一部分。

• 块级元素各占一行，让整份文档读起来像一份大纲。
• 子元素相对父元素缩进一级，使用与项目一致的空格/制表符宽度。
• 行内元素默认不打断，避免一段文本被强行拆成单词一行，破坏阅读节奏。
• `<pre>`、`<textarea>`、`<script>`、`<style>` 内部的空白原样保留，格式化器在这些边界外止步。
• 属性顺序、属性值、HTML 实体编码原样保留：要不要转义、要不要简化字符引用，这些决定权在写代码的人，不在格式化工具。

一句话原则：格式化必须让浏览器渲染出的页面完全一致。如果只是“缩进了一下”就让页面表现变了，那变化的就不是排版，而是别的东西，要立刻回退并定位。

如何使用这个工具

1. 先在 HTML 格式化 中准备一份有代表性的需要更适合审查的 HTML 片段和复制标记，不要一开始就处理最大或最敏感的真实内容。
2. 执行处理流程并生成在发布或嵌入前更便于审查的格式化 HTML 结果后，优先检查嵌套深度、属性、实体文本、内联脚本、内联样式，以及源内容究竟是真 HTML 还是转义文本，再判断结果是否真的可用。
3. 只有当结果已经适合用于模板审查、CMS 清理、片段分享和文档示例，并且不再触发这条风险提醒时，才复制或下载输出：格式化后的 HTML 仍可能在语义或安全上有问题，因此发布前还应在真实渲染上下文里检查。

HTML 格式化 示例

这个 HTML 格式化 示例使用有代表性的需要更适合审查的 HTML 片段和复制标记，展示生成后的在发布或嵌入前更便于审查的格式化 HTML 结果，便于你先确认嵌套深度、属性、实体文本、内联脚本、内联样式，以及源内容究竟是真 HTML 还是转义文本，再把同样设置用于真实输入。

示例输入

<main><h1>Tools</h1><p>Fast utilities.</p></main>

预期输出

<main>
  <h1>Tools</h1>
  <p>Fast utilities.</p>
</main>

把压平的片段重新还原成可审查的树形

<!-- 格式化前：CMS 或构建产物里常见的样子 -->
<article class="card"><header><h2>标题</h2><p class="meta">今天更新</p></header><section class="body"><p>这一段是文章的导读。</p><ul><li>第一条</li><li>第二条</li></ul></section></article>

<!-- 格式化后：可以扫读、可以做 diff -->
<article class="card">
  <header>
    <h2>标题</h2>
    <p class="meta">今天更新</p>
  </header>
  <section class="body">
    <p>这一段是文章的导读。</p>
    <ul>
      <li>第一条</li>
      <li>第二条</li>
    </ul>
  </section>
</article>

格式化 HTML 几乎立即回本的场景

HTML 的读者远远多于作者。下面这些场景里，先把 HTML 格式化一遍，往往就是“五分钟搞定”和“盯一小时”之间的区别。

• 审查 CMS 渲染出来的页面：编辑反馈“版式不对”，但你手上只有渲染后的 HTML，得先把树形还原出来。
• 从静态站点构建产物里抽离组件：流水线吐出来的 HTML 通常都是压平的，要先格式化才能定位边界。
• 对比两次发布之间同一页面的快照：HTML 不格式化的 diff 基本不可读，格式化之后差异会变得一目了然。
• 无障碍审查：地标结构、标题层级、ARIA 属性都需要看“树”而不是“字符串”，缩进版本审起来才靠谱。
• 教学或写文档：单行 HTML 没法让读者建立嵌套直觉，缩进版本才有教学价值。

格式化前最值得理解的几个边界

HTML 格式化器为什么大多“保守”？因为 HTML 比 JSON/CSS 这种格式藏了更多坑。下面这几个边界提前看一眼，能让你在遇到“奇怪的 diff”时迅速判断它是 bug 还是设计意图。

• `<pre>`、`<textarea>`、设置了 `white-space: pre` 的 `<code>`，以及行内元素之间的空格，都直接影响渲染。这些位置必须原样保留，不能随意换行或缩进。
• 自闭合写法 `<br/>` 与 `<br>` 在 HTML5 里等价，但 XHTML、某些模板引擎并不等价。格式化器不应在两者之间互改。
• 条件注释和模板占位符（`<!--[if IE]-->`、`{{ }}`、`{% %}`、`<?= ?>`）本质上不是 HTML，应原样穿过格式化器，不要被识别为“可整理”的内容。
• 内联 `<script>`、`<style>` 内部是 JS/CSS，不是 HTML，不要让 HTML 格式化器递归进去再格式化一遍。这两个语种应该由各自专门的格式化器来处理。
• 依赖元素间空格的布局：若干 `<span>` 标签之间的“空白也是间距”。强行让每个 span 一行可能会让原本紧凑的一行排列在渲染时挤在一起。

HTML 格式化器与相关工具的对比

使用注意

• 复用在发布或嵌入前更便于审查的格式化 HTML 结果前，先检查嵌套深度、属性、实体文本、内联脚本、内联样式，以及源内容究竟是真 HTML 还是转义文本。
• 格式化后的 HTML 仍可能在语义或安全上有问题，因此发布前还应在真实渲染上下文里检查。
• 当结果会影响生产工作或客户可见内容时，应保留原始需要更适合审查的 HTML 片段和复制标记以便回退和核对。

HTML 格式化 参考说明

HTML 格式化 的参考说明应始终围绕需要更适合审查的 HTML 片段和复制标记、生成的在发布或嵌入前更便于审查的格式化 HTML 结果，以及用于模板审查、CMS 清理、片段分享和文档示例前必须确认的检查点。

• 输入重点：需要更适合审查的 HTML 片段和复制标记。
• 输出重点：在发布或嵌入前更便于审查的格式化 HTML 结果。
• 复核重点：嵌套深度、属性、实体文本、内联脚本、内联样式，以及源内容究竟是真 HTML 还是转义文本。

参考资料

• WHATWG HTML Living Standard
• MDN: HTML