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