PHP小码农

Appearance

代码风格指南 ​

良好的 HTML 代码风格不仅使代码更易读、更易维护，还能减少错误和协作成本。本节将介绍 HTML 代码风格的核心要素：缩进规范、引号使用、属性顺序、自闭合标签、DOCTYPE 声明等，帮助团队建立一致的编码标准。

前置知识

阅读本节前，建议先了解：日期与货币格式

DOCTYPE 声明 ​

HTML5 使用简化的 DOCTYPE 声明：

html
<!-- HTML5 标准声明 -->
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>页面标题</title>
  </head>
  <body>
    <!-- 内容 -->
  </body>
</html>

不要省略 DOCTYPE

省略 <!DOCTYPE html> 会使浏览器进入怪异模式（Quirks Mode），导致渲染不一致。始终在 HTML 文件的第一行包含 DOCTYPE 声明。

缩进规范 ​

缩进方式 ​

方案优点缺点
2 空格（推荐）最常用，代码紧凑深层嵌套时不够明显
4 空格Python 风格，层次清晰代码宽度增加
Tab可配置宽度不同编辑器显示不同

推荐使用 2 空格缩进

2 空格是前端社区的主流选择，与 Vue、React、VitePress 等生态一致。

缩进示例 ​

html
<!-- 推荐：2 空格缩进 -->
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <title>页面标题</title>
  </head>
  <body>
    <header>
      <nav aria-label="主导航">
        <ul>
          <li><a href="/">首页</a></li>
          <li><a href="/about">关于</a></li>
        </ul>
      </nav>
    </header>
    <main>
      <h1>页面标题</h1>
      <p>正文内容...</p>
    </main>
  </body>
</html>

引号使用 ​

属性值引号 ​

HTML 属性值必须使用引号包裹。推荐使用双引号：

html
<!-- 推荐：双引号 -->
<div class="container" id="main" data-name="example">

<!-- 可接受：单引号 -->
<div class='container' id='main'>

<!-- 不推荐：不使用引号（仅在特定情况下有效） -->
<div class=container id=main>

<!-- 混合使用场景：属性值中包含引号时 -->
<button onclick="showMessage('Hello!')">点击</button>

嵌套引号 ​

html
<!-- 属性中使用引号时，内外引号不同 -->
<!-- 推荐：外双内单 -->
<div onclick="handleClick('item')" title="点击 &quot;提交&quot; 按钮">

<!-- 也可：外单内双 -->
<div onclick='handleClick("item")' title='点击 "提交" 按钮'>

属性顺序 ​

属性的排列顺序应遵循逻辑分类，便于快速定位：

html
<!-- 推荐的属性顺序 -->
<a
  href="/products"
  target="_blank"
  rel="noopener noreferrer"
  class="product-link"
  id="main-link"
  data-id="12345"
  aria-label="查看产品详情"
  onclick="trackClick(event)"
>
  查看产品
</a>

属性分类顺序 ​

顺序类别属性示例
1核心属性id、class
2行为属性href、src、type、action、method
3状态属性disabled、checked、selected、hidden
4ARIA 属性role、aria-label、aria-labelledby
5data 属性data-*
6事件属性onclick、onchange、onsubmit
html
<!-- 按顺序排列的属性 -->
<input
  id="email"
  class="form-input"
  type="email"
  name="email"
  required
  aria-describedby="email-error"
  data-validate="email"
  oninput="validateEmail(this)"
/>

布尔属性 ​

布尔属性不需要赋值：

html
<!-- 推荐：不赋值 -->
<input type="text" required>
<input type="checkbox" checked>
<button disabled>提交</button>
<div hidden>隐藏内容</div>

<!-- 可接受：显式赋值（XHTML 兼容） -->
<input type="text" required="required">
<input type="checkbox" checked="checked">
<button disabled="disabled">提交</button>

自闭合标签 ​

HTML5 中自闭合标签不需要尾部斜杠：

html
<!-- 推荐：HTML5 风格（无尾部斜杠） -->
<br>
<hr>
<img src="image.jpg" alt="描述">
<input type="text">
<meta charset="UTF-8">
<link rel="stylesheet" href="style.css">

<!-- 可接受：XHTML 风格（有尾部斜杠） -->
<br />
<hr />
<img src="image.jpg" alt="描述" />
<input type="text" />

一致性原则

选择一种风格并在整个项目中保持一致。新项目推荐 HTML5 风格（无尾部斜杠）。

标签大小写 ​

统一使用小写标签：

html
<!-- 推荐：小写 -->
<div class="container">
  <h1>标题</h1>
  <img src="photo.jpg" alt="照片">
</div>

<!-- 不推荐：大写或混合 -->
<DIV class="container">
  <H1>标题</H1>
  <IMG src="photo.jpg" alt="照片">
</DIV>

完整代码示例 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="页面描述内容">
    <title>代码风格示例</title>
    <link rel="stylesheet" href="styles/main.css">
  </head>
  <body>
    <!-- 跳过导航链接 -->
    <a href="#main-content" class="skip-link">跳到主要内容</a>

    <!-- 网站头部 -->
    <header class="site-header">
      <nav aria-label="主导航">
        <ul class="nav-list">
          <li class="nav-item">
            <a href="/" class="nav-link">首页</a>
          </li>
          <li class="nav-item">
            <a href="/products" class="nav-link">产品</a>
          </li>
          <li class="nav-item">
            <a href="/about" class="nav-link">关于</a>
          </li>
        </ul>
      </nav>
    </header>

    <!-- 主内容 -->
    <main id="main-content" class="site-main">
      <h1>欢迎访问</h1>
      <p>这是一个遵循代码风格指南的 HTML 页面示例。</p>

      <!-- 产品卡片 -->
      <article class="product-card" data-id="12345">
        <img
          src="images/product.jpg"
          alt="无线蓝牙耳机，黑色入耳式"
          class="product-image"
          width="300"
          height="200"
          loading="lazy"
        >
        <h2 class="product-title">无线蓝牙耳机</h2>
        <p class="product-price" data-price="299.00">¥299.00</p>
        <button
          type="button"
          class="btn btn-primary"
          aria-label="将无线蓝牙耳机加入购物车"
          onclick="addToCart(12345)"
        >
          加入购物车
        </button>
      </article>
    </main>

    <!-- 页脚 -->
    <footer class="site-footer">
      <p class="copyright">&copy; 2024 公司名称</p>
    </footer>

    <script src="scripts/main.js"></script>
  </body>
</html>

注意事项 ​

  1. 保持一致性：选择一种风格并在整个项目中统一使用
  2. 不要混合缩进：避免混用空格和 Tab
  3. 属性换行：超过 2-3 个属性时考虑换行
  4. 有意义命名：class 和 id 使用有语义的名称
  5. 编辑器配置：使用 .editorconfig 统一团队编辑器配置

最佳实践 ​

  • 使用 2 空格缩进
  • 属性值使用双引号
  • 布尔属性不赋值
  • HTML5 自闭合标签不加尾部斜杠
  • 标签和属性名使用小写
  • 按类别顺序排列属性
  • 长属性列表进行换行
  • 使用 .editorconfig 统一团队规范

下一节

继续学习：缩进与格式化

参考链接 ​