前端代码规范 v1.0

制定部门：前端技术委员会
版本：1.0
生效日期：YYYY-MM-DD
审批人：______

一、总则

1.1 目的

统一团队 HTML/CSS 编码风格，提升代码可读性、可维护性、可访问性，降低协作成本，确保项目健康度。

1.2 适用范围

本规范适用于公司所有 Web 项目的 HTML、CSS（含预处理器）代码编写及审查。第三方库文件除外。

1.3 核心原则

一致性：所有成员必须严格遵守统一标准。
可维护性：代码应清晰表达意图，便于他人理解。
性能与可访问性：不因样式损害页面性能和用户体验。
工具化优先：能由工具强制检查的规则，不得依赖人工记忆。

二、HTML 规范

2.1 文档骨架

始终使用 <!DOCTYPE html>，必须声明 lang 属性。
必须包含正确的字符集和视口元标签。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>页面标题</title>
</head>

2.2 语义与结构

优先使用语义化标签：<header>, <nav>, <main>, <section>, <article>, <aside>, <footer>。
标题结构应有层次，不跳级（h1>h2>h3）。
严禁使用纯表现性标签（如 <b>, <i>, <font>），样式交由 CSS 处理。

2.3 代码风格

标签名、属性名一律小写。
属性值使用双引号包裹。
缩进：2 个空格，禁止 Tab 混用。
自闭合标签（如 <br>, <img>, <input>）统一不使用 / 闭合（<br>）。
布尔属性仅写属性名，不赋值：<input type="checkbox" checked>。
属性顺序（推荐）：class → id → data-* → 其他属性。

2.4 可访问性（A11y）

所有 <img> 必须拥有 alt 属性，纯装饰图片设为 alt=""。

表单控件必须关联 <label>，方式如下：

<label for="email">邮箱</label>
<input type="email" id="email">

使用 ARIA 属性描述非标准交互组件，如 role="tab", aria-expanded 等。
跳过导航链接需提供，以辅助键盘用户。

2.5 资源加载与性能

样式文件放在 <head> 中（避免 FOUC）。
脚本文件放在 </body> 前，或使用 defer/async 属性。
使用响应式图片技术，如 srcset, <picture>。
图片和 iframe 添加 loading="lazy" 进行懒加载。

2.6 代码分离与注释

严禁内联样式（style="..."），样式由 CSS 实现。
严禁内联事件（onclick="..."），行为由 JS 绑定。
区块闭合标签后添加清晰注释（可选，视页面复杂度）：
```
<div class="main-content">
  ...
</div>
```

三、CSS 规范

3.1 命名约定 —— BEM

强制使用 BEM（Block__Element--Modifier） 命名法，确保模块独立性和可读性。

/* Block */
.card { }

/* Element */
.card__title { }
.card__image { }

/* Modifier */
.card--featured { }
.card__title--large { }

命名空间补充（强烈推荐）

.l- 或 .layout-：布局
.js-：JavaScript 钩子（此类名不得用于样式）
.is-、.has-：状态类（如 .is-active, .has-error）
.u-：工具类（如 .u-hidden）

3.2 代码格式化

缩进：2 个空格。
声明块左花括号前空一格，右花括号独占一行。
每条声明一行，结尾分号不可省略。
属性值引号：双引号或单引号统一，推荐 content: ""; 使用双引号。
颜色值：尽可能短小写，如 #fff；具备透明度时可用 rgba() 或 8 位十六进制 #RRGGBBAA。
0 值不加单位：margin: 0;，而非 margin: 0px;。

属性排序规则（任选一种，全项目统一）
方案 A - 分组排序（Airbnb 风格）：
显示 → 定位 → 盒模型 → 排版 → 视觉 → 其他
display, position, top, width, height, margin, padding, font, color, background, border, opacity, ...

方案 B - 字母排序：
适用于自动格式化（Prettier/Stylelint 可强制）。

3.3 选择器规范

禁止使用 ID 选择器 作为样式钩子，仅用于 JS 或锚点。
嵌套深度不超过 3 层（含 & 父引用）。
谨慎使用 !important，仅允许在工具类 .u-hidden 或覆盖第三方样式时使用，且需注释说明。
避免使用通配符 * 做重设，改用具体选择器。

3.4 响应式与移动优先

基础样式以最小屏幕为基准，通过 min-width 媒体查询渐进增强。

断点统一使用 预定义变量（Sass/Less/CSS 自定义属性），严禁直接写数值。

$screen-sm: 576px;
$screen-md: 768px;
$screen-lg: 992px;

@media (min-width: $screen-md) { ... }

媒体查询紧贴相关选择器内部编写（Sass 嵌套），避免分散文件。

3.5 注释规范

所有复杂模块必须添加节注释，包含说明、作者、依赖关系。

格式建议：

/* ==========================================================================
   组件：卡片列表 (Card List)
   依赖：.card 组件
   ========================================================================== */

特殊值或 hack 需简短行内注释。

3.6 架构与组织（7-1 模式）

采用分层架构，文件组织遵循 7-1 模式：

styles/
  abstracts/   (变量、混合宏、函数)
  base/        (重置、排版、通用基础)
  components/  (独立组件样式)
  layout/      (布局、网格、头部、页脚)
  pages/       (页面特有样式，少量)
  themes/      (主题、暗色模式)
  utilities/   (工具类，如 .u-text-center)

main.scss 仅做文件索引，禁止直接编写样式代码。

3.7 现代特性

全局设置 box-sizing: border-box。
布局优先使用 Flexbox 和 Grid，逐步淘汰浮动布局。

使用 CSS 自定义属性（变量）管理公共值：

:root {
  --color-primary: #1890ff;
  --spacing-unit: 8px;
}

四、自动化强制工具

约定依赖工具落地，所有项目必须集成以下配置。

4.1 EditorConfig（编辑器统一）

root = true

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

4.2 Prettier 格式化（HTML/CSS）

{
  "printWidth": 100,
  "tabWidth": 2,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true,
  "semi": true
}

4.3 Stylelint 规则（CSS）

核心配置（使用 stylelint-config-standard 或自定义）：

{
  "extends": "stylelint-config-standard",
  "rules": {
    "selector-max-id": 0,
    "selector-max-depth": 3,
    "declaration-no-important": [true, { "severity": "warning" }],
    "color-hex-length": "short",
    "number-leading-zero": "never",
    "plugin/declaration-block-order": [ ... ] // 按分组排序
  }
}

4.4 HTMLHint（基本检查）

{
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "attr-value-double-quotes": true,
  "id-unique": true,
  "alt-require": true,
  "doctype-first": true,
  "style-disabled": true
}

4.5 持续集成

在 CI/CD 流水线中强制执行 stylelint, htmlhint 检查，不通过则禁止合并。

五、代码审查关注点

命名是否遵循 BEM？有无 ID 选择器？
是否有内联样式或事件？
alt 属性是否齐全？表单有无关联 label？
嵌套是否超过 3 层？响应式是否移动优先？
是否有未加注释的 !important 或魔术数字？

六、附录

6.1 术语表

BEM：Block Element Modifier，一种 CSS 命名方法论。
FOUC：Flash of Unstyled Content，无样式内容闪烁。
A11y：Accessibility 的缩写，可访问性。

6.2 参考资料

颁布即执行，修订需由前端技术委员会评审通过。

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - 华腾智算