PHP小码农

Appearance

缩进与格式化 ​

HTML 代码的格式化直接影响代码的可读性和维护性。合理的缩进规则、长行换行策略、多属性换行规范，以及自动化格式化工具的配置，是每个前端团队必须建立的基础规范。本节将详细介绍 HTML 格式化的核心规则和 Prettier 配置方法。

前置知识

阅读本节前，建议先了解：代码风格指南

嵌套缩进规则 ​

基本缩进 ​

每个嵌套层级增加 2 个空格：

html
<!-- 正确：每级缩进 2 空格 -->
<body>
  <header>
    <nav>
      <ul>
        <li>
          <a href="/">首页</a>
        </li>
      </ul>
    </nav>
  </header>
  <main>
    <article>
      <h2>标题</h2>
      <p>内容</p>
    </article>
  </main>
</body>

特殊情况的缩进 ​

html
<!-- 列表项内容较短时可单行 -->
<ul>
  <li><a href="/">首页</a></li>
  <li><a href="/products">产品</a></li>
  <li><a href="/about">关于</a></li>
</ul>

<!-- 列表项内容较长时换行缩进 -->
<ul>
  <li>
    <a href="/products/wireless-headphones-pro">
      无线蓝牙耳机 Pro - 高品质降噪
    </a>
  </li>
</ul>

<!-- 表格缩进 -->
<table>
  <thead>
    <tr>
      <th scope="col">名称</th>
      <th scope="col">价格</th>
      <th scope="col">库存</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>无线耳机</td>
      <td>¥299.00</td>
      <td>128</td>
    </tr>
  </tbody>
</table>

长行换行 ​

行宽限制 ​

推荐将每行 HTML 代码限制在 80-120 个字符以内：

html
<!-- 行过长（不推荐） -->
<a href="https://example.com/products/wireless-bluetooth-headphone-pro-black-2024-edition" class="product-link" id="product-12345" data-category="electronics" aria-label="查看无线蓝牙耳机 Pro 详情">查看详情</a>

<!-- 换行后（推荐） -->
<a
  href="https://example.com/products/wireless-bluetooth-headphone-pro"
  class="product-link"
  id="product-12345"
  data-category="electronics"
  aria-label="查看无线蓝牙耳机 Pro 详情"
>
  查看详情
</a>

多属性换行 ​

当元素属性超过 2-3 个时，建议换行：

html
<!-- 少量属性：单行 -->
<input type="text" id="name" name="name" required>

<!-- 多属性：换行 -->
<input
  type="email"
  id="user-email"
  class="form-control form-control-lg"
  name="email"
  placeholder="请输入邮箱"
  required
  aria-describedby="email-hint"
  autocomplete="email"
  data-validate="email"
>

换行缩进对齐 ​

html
<!-- 方式 1：每个属性一行，对齐到标签后 -->
<input
  type="email"
  id="email"
  class="form-input"
  name="email"
  required
>

<!-- 方式 2：每个属性一行，对齐到首字母（不推荐，维护成本高） -->
<input
       type="email"
       id="email"
       class="form-input"
       name="email"
       required
>

<!-- 推荐：方式 1（不强制对齐，减少维护成本） -->

空行使用 ​

空行规范 ​

html
<!-- 在逻辑块之间使用空行分隔 -->
<header>...</header>
                             <!-- 空行 -->
<main>
  <h1>标题</h1>
                             <!-- 空行 -->
  <p>第一段内容...</p>
                             <!-- 空行 -->
  <p>第二段内容...</p>
                             <!-- 空行 -->
  <section>
    <h2>子标题</h2>
    <p>子内容...</p>
  </section>
</main>
                             <!-- 空行 -->
<footer>...</footer>

注释前空行 ​

html
<!-- 注释前使用空行 -->
<main>
  <h1>标题</h1>

  <!-- 产品列表 -->
  <section class="products">
    ...
  </section>

  <!-- 相关推荐 -->
  <aside class="recommendations">
    ...
  </aside>
</main>

Prettier 配置 ​

Prettier 是目前最流行的代码格式化工具，支持 HTML 格式化。

安装 Prettier ​

bash
# 安装 Prettier
npm install --save-dev prettier

# 或全局安装
npm install -g prettier

配置文件 ​

在项目根目录创建 .prettierrc 文件：

json
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": false,
  "singleQuote": true,
  "htmlWhitespaceSensitivity": "css",
  "htmlSingleAttributePerLine": true,
  "bracketSameLine": false,
  "singleAttributePerLine": true,
  "trailingComma": "es5"
}

Prettier HTML 相关配置 ​

选项默认值说明
printWidth80每行最大字符数
tabWidth2缩进宽度
useTabsfalse使用 Tab 还是空格
htmlWhitespaceSensitivitycssHTML 空白敏感度
singleAttributePerLinefalse每行一个属性
bracketSameLinefalse> 是否与最后一个属性同行

EditorConfig 配置 ​

.editorconfig 确保团队成员使用一致的编辑器设置：

ini
# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

[*.html]
indent_size = 2

[*.{js,ts,json,css,scss}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

package.json scripts ​

json
{
  "scripts": {
    "format": "prettier --write \"**/*.html\"",
    "format:check": "prettier --check \"**/*.html\"",
    "format:html": "prettier --write \"src/**/*.html\""
  }
}

VS Code 配置 ​

json
// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "html.format.indentSize": 2,
  "html.format.wrapLineLength": 100,
  "html.format.wrapAttributes": "auto"
}

自动格式化效果 ​

格式化前 ​

html
<!DOCTYPE html>
<html lang="zh-CN"><head><meta charset="UTF-8"><title>测试</title>
<link rel="stylesheet" href="style.css"></head><body>
<header><nav aria-label="主导航"><ul><li><a href="/" class="nav-link active" data-page="home">首页</a></li><li><a href="/products" class="nav-link" data-page="products">产品</a></li></ul></nav></header>
<main><h1>欢迎</h1><p>内容</p></main></body></html>

格式化后 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <title>测试</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <header>
      <nav aria-label="主导航">
        <ul>
          <li>
            <a
              href="/"
              class="nav-link active"
              data-page="home"
            >
              首页
            </a>
          </li>
          <li>
            <a
              href="/products"
              class="nav-link"
              data-page="products"
            >
              产品
            </a>
          </li>
        </ul>
      </nav>
    </header>
    <main>
      <h1>欢迎</h1>
      <p>内容</p>
    </main>
  </body>
</html>

注意事项 ​

  1. 不要手动格式化：使用 Prettier 等工具自动格式化
  2. 配置与团队对齐：确保所有成员使用相同的 Prettier 配置
  3. CI 集成：在 CI 中检查格式，阻止不合规代码合并
  4. 格式化不应改变语义：确保格式化不会影响页面渲染
  5. 考虑 VitePress 限制：Markdown 中的 HTML 嵌套需要额外注意

最佳实践 ​

  • 在项目中配置 Prettier 和 EditorConfig
  • 设置编辑器保存时自动格式化
  • 在 CI 流程中添加格式检查
  • 使用 singleAttributePerLine: true 提高多属性可读性
  • 保持 printWidth 在 80-120 之间
  • 在版本控制中提交格式化配置文件

下一节

继续学习：命名约定

参考链接 ​