前端代码规范 v1.0

以下是一份可直接颁布的《前端代码规范（HTML/CSS）》，基于高认可度的行业实践制定，包含约定细则、示例与自动化配置。你可按需补充公司名称、版本日期后正式发布。

前端代码规范 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><!-- /.main-content -->

三、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 参考资料

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

posted @ 2026-07-15 16:53  华腾智算  阅读(3)  评论(0)    收藏  举报
https://damo.alibaba.com/ https://tianchi.aliyun.com/course?spm=5176.21206777.J_3941670930.5.87dc17c9BZNvLL