开发

CSS 开发标准 ​

前端开发标准系列 · 广州一千河科技有限公司 · 2026 年 11 月

文档版本控制 ​

版本号修订时间修订者备注
V1.02026/11/08初稿

1. 文件信息 ​

1.1. 编制依据 ​

本标准以阿里巴巴前端规约《CSS 编码规约》为基础，用于公司前端项目的样式编写和代码评审。

参考地址：阿里巴巴前端规约 CSS 编码规约

1.2. 适用范围和规则等级 ​

适用于公司维护的 CSS 样式表、CSS Modules 及 Sass 和 Less 源文件。格式规则适用于手写源码，预处理器规则适用于采用相应语言的项目。

强制条款须满足。推荐条款默认采用，参考条款用于指导实现。

2. CSS 编码 ​

2.1. 声明和排版 ​

强制 属性声明以分号结束，块内最后一条声明也保留分号。

推荐 每级缩进使用 2 个空格。选择器与左大括号之间留一个空格，每条属性声明和右大括号分别独占一行。

推荐 属性名紧跟冒号，冒号后留一个空格。组合器 >、+、~、|| 两侧各留一个空格。同一行中逗号后留一个空格。

推荐 注释分隔符与正文之间留一个空格。每行宜在 100 字符以内，url() 和无法安全拆行的值可例外。

参考 多个选择器逐行书写，单声明块也写成多行。注释前留一空行，块首或紧跟上一条注释时可省略。

2.2. 选择器 ​

参考 组件样式优先使用类选择器。避免 ID 选择器带来的高优先级，组合选择器宜控制在 3 个组成部分以内。

参考 属性选择器的值使用双引号。高频组件尽量少用宽泛的属性前缀匹配。

2.2.1. 类名定义 ​

推荐 采用 BEM 命名减少冲突。Block 表示独立块，Element 表示块内组成部分，Modifier 表示状态或变体。

例如 user-card 表示组件，user-card__header 表示内部区域，user-card--disabled 表示禁用状态。修饰类与被修饰的基础类一起使用。

html
<article class="user-card user-card--disabled">
  <h2 class="user-card__header">用户信息</h2>
</article>

2.3. 属性和值 ​

推荐 十六进制颜色使用小写，可缩写时用最短等价值。长度为零且语法允许时省略单位。

推荐 优先调整选择器或样式加载顺序处理覆盖，避免依赖 !important。

参考 保留小数点前的零，例如 0.5 和 -0.5px。同项目保持一致。

参考 相关声明分组，按定位、盒模型、文字排版、外观、其他的顺序编排。

参考 只改一个子属性时使用长写属性。合并多个属性前检查简写是否会重置其他值。

css
.notice > .notice__text,
.notice[data-state="active"] {
  position: relative;
  margin: 0;
  padding: 8px 12px;
  color: #333;
  background-color: #fff;
  opacity: 0.9;
}

2.4. 样式加载 ​

推荐 避免在浏览器端通过 CSS @import 串联样式表。入口样式使用 HTML 的 <link rel="stylesheet">，或在构建阶段由项目入口组织。

3. Sass 和 Less ​

3.1. 模块和表达式 ​

推荐 文件按模块引入、全局变量、样式规则排列。Dart Sass 用 @use 加载模块，模块入口需要转发成员时用 @forward。Less 的依赖引入放在样式规则前。

推荐 算术运算符两侧留空格。Dart Sass 除法用 math.div()，Less 除法加括号。

推荐 Mixin 名紧跟左括号。参数之间用逗号和一个空格分隔。

3.2. 块内顺序和嵌套 ​

推荐 块内依次写属性、Mixin、嵌套规则。嵌套前空一行，深度宜在 3 层内。

推荐 用 Mixin 复用样式。慎用 Sass @extend，尤其是在嵌套规则中。

推荐 源码注释可用 //。块注释是否保留取决于编译和压缩设置。

scss
/* SCSS */
@use "sass:math";

$card-width: 320px;

@mixin inset($y, $x) {
  padding: $y $x;
}

.card {
  width: math.div($card-width, 2);
  @include inset(8px, 12px);

  .card__title {
    margin: 0;
  }
}
less
/* Less */
@card-width: 320px;

.card {
  width: (@card-width / 2);
}