HTML 代码规范：从入门到精通 - 极速工具箱

引言

良好的 HTML 代码规范是前端开发的基础。无论是个人项目还是团队协作，遵循统一的规范都能让代码更加优雅、可维护。

基础规范

1. 文档声明

每个 HTML 文件必须以 DOCTYPE 声明开头：

<!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>

2. 字符编码

必须在 <head> 中声明 UTF-8 编码：

<meta charset="UTF-8">

3. 语言属性

<html> 标签应设置 lang 属性：

<html lang="zh-CN">  <!-- 中文 -->
<html lang="en">     <!-- 英文 -->

标签规范

1. 标签小写

<!-- 正确 -->
<div class="box">内容</div>

<!-- 错误 -->
<DIV CLASS="box">内容</DIV>

2. 属性值双引号

<!-- 正确 -->
<img src="image.jpg" alt="图片">

<!-- 不推荐 -->
<img src='image.jpg' alt='图片'>

3. 自闭合标签

HTML5 中自闭合标签无需斜杠：

<!-- 推荐 -->
<br>
<img src="image.jpg" alt="图片">
<input type="text">

<!-- 不推荐 -->
<br />
<img src="image.jpg" alt="图片" />

4. 标签闭合

所有标签必须正确闭合：

<!-- 正确 -->
<p>段落一</p>
<p>段落二</p>

<!-- 错误 -->
<p>段落一
<p>段落二

缩进规范

1. 统一缩进方式

<!-- 4 空格缩进（推荐） -->
<div>
    <p>内容</p>
</div>

<!-- 2 空格缩进 -->
<div>
  <p>内容</p>
</div>

建议：团队统一选择一种，推荐 4 空格。

2. 嵌套层级

<!-- 推荐：层级清晰 -->
<div class="card">
    <div class="card-header">
        <h3>标题</h3>
    </div>
    <div class="card-body">
        <p>内容</p>
    </div>
</div>

<!-- 不推荐：层级过深 -->
<div>
    <div>
        <div>
            <div>
                <div>
                    <div>
                        <p>内容</p>
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>

建议：嵌套不超过 5 层。

命名规范

1. class 命名

<!-- 推荐：kebab-case -->
<div class="nav-item"></div>
<div class="btn-primary"></div>

<!-- 不推荐 -->
<div class="navItem"></div>      <!-- 驼峰 -->
<div class="nav_item"></div>     <!-- 下划线 -->
<div class="NavItem"></div>      <!-- 大写开头 -->

2. id 命名

<!-- 推荐 -->
<div id="main-content"></div>

<!-- 不推荐 -->
<div id="mainContent"></div>
<div id="123"></div>  <!-- 数字开头 -->

3. BEM 命名法

<!-- Block__Element--Modifier -->
<div class="card">
    <div class="card__header">
        <h3 class="card__title card__title--large">标题</h3>
    </div>
    <div class="card__body">
        <p class="card__text">内容</p>
    </div>
</div>

语义化规范

1. 使用语义化标签

<!-- 推荐 -->
<header>
    <nav>...</nav>
</header>
<main>
    <article>...</article>
</main>
<footer>...</footer>

<!-- 不推荐 -->
<div class="header">
    <div class="nav">...</div>
</div>
<div class="main">
    <div class="article">...</div>
</div>
<div class="footer">...</div>

2. 标题层级

<!-- 正确：不跳级 -->
<h1>主标题</h1>
<h2>副标题</h2>
<h3>小标题</h3>

<!-- 错误：跳级 -->
<h1>主标题</h1>
<h4>跳级了</h4>

可访问性规范

1. 图片 alt 属性

<!-- 有内容的图片 -->
<img src="product.jpg" alt="红色连衣裙">

<!-- 装饰性图片 -->
<img src="divider.png" alt="" role="presentation">

<!-- 图标 -->
<button aria-label="搜索">
    <i class="icon-search"></i>
</button>

2. 表单关联 label

<!-- 推荐 -->
<label for="username">用户名</label>
<input type="text" id="username" name="username">

<!-- 或者包裹 -->
<label>
    用户名
    <input type="text" name="username">
</label>

<!-- 不推荐 -->
用户名
<input type="text" name="username">

3. ARIA 属性

<!-- 进度条 -->
<div role="progressbar" 
     aria-valuenow="75" 
     aria-valuemin="0" 
     aria-valuemax="100">
    75%
</div>

<!-- 展开/折叠 -->
<button aria-expanded="false" aria-controls="panel">
    展开
</button>
<div id="panel" hidden>
    内容...
</div>

性能规范

1. 资源加载

<!-- CSS 放在 head -->
<head>
    <link rel="stylesheet" href="style.css">
</head>

<!-- JS 放在 body 底部或使用 defer -->
<body>
    <!-- 内容 -->
    <script src="script.js" defer></script>
</body>

2. 图片优化

<!-- 指定尺寸，避免布局偏移 -->
<img src="image.jpg" alt="描述" width="800" height="600">

<!-- 懒加载 -->
<img src="image.jpg" alt="描述" loading="lazy">

<!-- 响应式图片 -->
<picture>
    <source srcset="image.webp" type="image/webp">
    <img src="image.jpg" alt="描述">
</picture>

3. 预加载关键资源

<link rel="preload" href="font.woff2" as="font" crossorigin>
<link rel="preconnect" href="https://api.example.com">

注释规范

1. 模块注释

<!-- ==================== 头部导航 ==================== -->
<header>
    <nav>...</nav>
</header>

<!-- ==================== 主要内容 ==================== -->
<main>
    ...
</main>

2. 功能注释

<!-- 轮播图组件 -->
<div class="carousel">
    <!-- 轮播项 -->
    <div class="carousel-item">...</div>
    <div class="carousel-item">...</div>
  
    <!-- 控制按钮 -->
    <button class="carousel-prev">上一张</button>
    <button class="carousel-next">下一张</button>
</div>

3. TODO 标记

<!-- TODO: 添加移动端适配 -->
<div class="desktop-only">...</div>

<!-- FIXME: 在 Safari 下显示异常 -->
<div class="special-effect">...</div>

常见错误

错误一：div 滥用

<!-- 不推荐 -->
<div class="header">
    <div class="logo">
        <div class="logo-text">Logo</div>
    </div>
</div>

<!-- 推荐 -->
<header>
    <div class="logo">
        <span class="logo-text">Logo</span>
    </div>
</header>

错误二：内联样式过多

<!-- 不推荐 -->
<div style="color: red; font-size: 16px; margin: 10px;">

<!-- 推荐 -->
<div class="error-message">

错误三：忽略移动端

<!-- 必须添加 viewport -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">

检查工具

工具	用途
W3C Validator	HTML 语法验证
Lighthouse	性能与可访问性检查
HTMLHint	代码规范检查
axe	可访问性检测

总结

良好的 HTML 代码规范是专业前端的基础。从文档结构、标签使用、命名规范到可访问性，每个细节都影响代码质量。坚持规范，让代码更优雅。

引言