|
1 | 1 | # css-style-guide
|
2 | 2 |
|
3 |
| -css-style-guide |
| 3 | +css 代码规范,在 [airbnb] 基础上修改,改用 stylelint 作为规则检查器 |
| 4 | + |
| 5 | +> 代码是由人来书写和维护的,保持可维护性第一原则。 |
| 6 | +
|
| 7 | +source: https://github.com/Zhangjd/css-style-guide |
| 8 | + |
| 9 | +# Airbnb CSS / Sass 指南 |
| 10 | + |
| 11 | +*用更合理的方式写 CSS 和 Sass* |
| 12 | + |
| 13 | +翻译自 [Airbnb CSS / Sass Styleguide](https://github.com/airbnb/css) |
| 14 | + |
| 15 | + |
| 16 | +## 目录 |
| 17 | + |
| 18 | + 1. [术语](#terminology) |
| 19 | + - [规则声明](#rule-declaration) |
| 20 | + - [选择器](#selectors) |
| 21 | + - [属性](#properties) |
| 22 | + 1. [CSS](#css) |
| 23 | + - [格式](#formatting) |
| 24 | + - [注释](#comments) |
| 25 | + - [OOCSS 和 BEM](#oocss-and-bem) |
| 26 | + - [ID 选择器](#id-selectors) |
| 27 | + - [JavaScript 钩子](#javascript-hooks) |
| 28 | + - [边框](#border) |
| 29 | + 1. [Sass](#sass) |
| 30 | + - [语法](#syntax) |
| 31 | + - [排序](#ordering-of-property-declarations) |
| 32 | + - [变量](#variables) |
| 33 | + - [Mixins](#mixins) |
| 34 | + - [扩展指令](#extend-directive) |
| 35 | + - [嵌套选择器](#nested-selectors) |
| 36 | + |
| 37 | +<a name="terminology"></a> |
| 38 | +## 术语 |
| 39 | + |
| 40 | +<a name="rule-declaration"></a> |
| 41 | +### 规则声明 |
| 42 | + |
| 43 | +我们把一个(或一组)选择器和一组属性称之为 “规则声明”。举个例子: |
| 44 | + |
| 45 | +```css |
| 46 | +.listing { |
| 47 | + font-size: 18px; |
| 48 | + line-height: 1.2; |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +<a name="selectors"></a> |
| 53 | +### 选择器 |
| 54 | + |
| 55 | +在规则声明中,“选择器” 负责选取 DOM 树中的元素,这些元素将被定义的属性所修饰。选择器可以匹配 HTML 元素,也可以匹配一个元素的类名、ID, 或者元素拥有的属性。以下是选择器的例子: |
| 56 | + |
| 57 | +```css |
| 58 | +.my-element-class { |
| 59 | + /* ... */ |
| 60 | +} |
| 61 | + |
| 62 | +[aria-hidden] { |
| 63 | + /* ... */ |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +<a name="properties"></a> |
| 68 | +### 属性 |
| 69 | + |
| 70 | +最后,属性决定了规则声明里被选择的元素将得到何种样式。属性以键值对形式存在,一个规则声明可以包含一或多个属性定义。以下是属性定义的例子: |
| 71 | + |
| 72 | +```css |
| 73 | +/* some selector */ { |
| 74 | + background: #f1f1f1; |
| 75 | + color: #333; |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +<a name="css"></a> |
| 80 | +## CSS |
| 81 | + |
| 82 | +<a name="formatting"></a> |
| 83 | +### 格式 |
| 84 | + |
| 85 | +* 使用 2 个空格作为缩进。 |
| 86 | +* 类名建议使用破折号代替驼峰法。如果你使用 BEM,也可以使用下划线(参见下面的 [OOCSS 和 BEM](#oocss-and-bem))。 |
| 87 | +* 不要使用 ID 选择器。 |
| 88 | +* 在一个规则声明中应用了多个选择器时,每个选择器独占一行。 |
| 89 | +* 在规则声明的左大括号 `{` 前加上一个空格。 |
| 90 | +* 在属性的冒号 `:` 后面加上一个空格,前面不加空格。 |
| 91 | +* 规则声明的右大括号 `}` 独占一行。 |
| 92 | +* 规则声明之间用空行分隔开。 |
| 93 | + |
| 94 | +**Bad** |
| 95 | + |
| 96 | +```css |
| 97 | +.avatar{ |
| 98 | + border-radius:50%; |
| 99 | + border:2px solid white; } |
| 100 | +.no, .nope, .not_good { |
| 101 | + // ... |
| 102 | +} |
| 103 | +#lol-no { |
| 104 | + // ... |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +**Good** |
| 109 | + |
| 110 | +```css |
| 111 | +.avatar { |
| 112 | + border-radius: 50%; |
| 113 | + border: 2px solid white; |
| 114 | +} |
| 115 | + |
| 116 | +.one, |
| 117 | +.selector, |
| 118 | +.per-line { |
| 119 | + // ... |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +<a name="comments"></a> |
| 124 | +### 注释 |
| 125 | + |
| 126 | +* 建议使用行注释 (在 Sass 中是 `//`) 代替块注释。 |
| 127 | +* 建议注释独占一行。避免行末注释。 |
| 128 | +* 给没有自注释的代码写上详细说明,比如: |
| 129 | + - 为什么用到了 z-index |
| 130 | + - 兼容性处理或者针对特定浏览器的 hack |
| 131 | + |
| 132 | +<a name="oocss-and-bem"></a> |
| 133 | +### OOCSS 和 BEM |
| 134 | + |
| 135 | +出于以下原因,我们鼓励使用 OOCSS 和 BEM 的某种组合: |
| 136 | + |
| 137 | + * 可以帮助我们理清 CSS 和 HTML 之间清晰且严谨的关系。 |
| 138 | + * 可以帮助我们创建出可重用、易装配的组件。 |
| 139 | + * 可以减少嵌套,降低特定性。 |
| 140 | + * 可以帮助我们创建出可扩展的样式表。 |
| 141 | + |
| 142 | +**OOCSS**,也就是 “Object Oriented CSS(面向对象的CSS)”,是一种写 CSS 的方法,其思想就是鼓励你把样式表看作“对象”的集合:创建可重用性、可重复性的代码段让你可以在整个网站中多次使用。 |
| 143 | + |
| 144 | +参考资料: |
| 145 | + |
| 146 | + * Nicole Sullivan 的 [OOCSS wiki](https://github.com/stubbornella/oocss/wiki) |
| 147 | + * Smashing Magazine 的 [Introduction to OOCSS](http://www.smashingmagazine.com/2011/12/12/an-introduction-to-object-oriented-css-oocss/) |
| 148 | + |
| 149 | +**BEM**,也就是 “Block-Element-Modifier”,是一种用于 HTML 和 CSS 类名的_命名约定_。BEM 最初是由 Yandex 提出的,要知道他们拥有巨大的代码库和可伸缩性,BEM 就是为此而生的,并且可以作为一套遵循 OOCSS 的参考指导规范。 |
| 150 | + |
| 151 | + * CSS Trick 的 [BEM 101](https://css-tricks.com/bem-101/) |
| 152 | + * Harry Roberts 的 [introduction to BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) |
| 153 | + |
| 154 | +**示例** |
| 155 | + |
| 156 | +```html |
| 157 | +<article class="listing-card listing-card--featured"> |
| 158 | + |
| 159 | + <h1 class="listing-card__title">Adorable 2BR in the sunny Mission</h1> |
| 160 | + |
| 161 | + <div class="listing-card__content"> |
| 162 | + <p>Vestibulum id ligula porta felis euismod semper.</p> |
| 163 | + </div> |
| 164 | + |
| 165 | +</article> |
| 166 | +``` |
| 167 | + |
| 168 | +```css |
| 169 | +.listing-card { } |
| 170 | +.listing-card--featured { } |
| 171 | +.listing-card__title { } |
| 172 | +.listing-card__content { } |
| 173 | +``` |
| 174 | + |
| 175 | + * `.listing-card` 是一个块(block),表示高层次的组件。 |
| 176 | + * `.listing-card__title` 是一个元素(element),它属于 `.listing-card` 的一部分,因此块是由元素组成的。 |
| 177 | + * `.listing-card--featured` 是一个修饰符(modifier),表示这个块与 `.listing-card` 有着不同的状态或者变化。 |
| 178 | + |
| 179 | +<a name="id-selectors"></a> |
| 180 | +### ID 选择器 |
| 181 | + |
| 182 | +在 CSS 中,虽然可以通过 ID 选择元素,但大家通常都会把这种方式列为反面教材。ID 选择器给你的规则声明带来了不必要的高[优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity),而且 ID 选择器是不可重用的。 |
| 183 | + |
| 184 | +想要了解关于这个主题的更多内容,参见 [CSS Wizardry 的文章](http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/),文章中有关于如何处理优先级的内容。 |
| 185 | + |
| 186 | +<a name="javascript-hooks"></a> |
| 187 | +### JavaScript 钩子 |
| 188 | + |
| 189 | +避免在 CSS 和 JavaScript 中绑定相同的类。否则开发者在重构时通常会出现以下情况:轻则浪费时间在对照查找每个要改变的类,重则因为害怕破坏功能而不敢作出更改。 |
| 190 | + |
| 191 | +我们推荐在创建用于特定 JavaScript 的类名时,添加 `.js-` 前缀: |
| 192 | + |
| 193 | +```html |
| 194 | +<button class="btn btn-primary js-request-to-book">Request to Book</button> |
| 195 | +``` |
| 196 | + |
| 197 | +<a name="border"></a> |
| 198 | +### 边框 |
| 199 | + |
| 200 | +在定义无边框样式时,使用 `0` 代替 `none`。 |
| 201 | + |
| 202 | +**Bad** |
| 203 | + |
| 204 | +```css |
| 205 | +.foo { |
| 206 | + border: none; |
| 207 | +} |
| 208 | +``` |
| 209 | + |
| 210 | +**Good** |
| 211 | + |
| 212 | +```css |
| 213 | +.foo { |
| 214 | + border: 0; |
| 215 | +} |
| 216 | +``` |
| 217 | + |
| 218 | +<a name="sass"></a> |
| 219 | +## Sass |
| 220 | + |
| 221 | +<a name="syntax"></a> |
| 222 | +### 语法 |
| 223 | + |
| 224 | +* 使用 `.scss` 的语法,不使用 `.sass` 原本的语法。 |
| 225 | +* CSS 和 `@include` 声明按照以下逻辑排序(参见下文) |
| 226 | + |
| 227 | +<a name="ordering-of-property-declarations"></a> |
| 228 | +### 属性声明的排序 |
| 229 | + |
| 230 | +1. 属性声明 |
| 231 | + |
| 232 | + 首先列出除去 `@include` 和嵌套选择器之外的所有属性声明。 |
| 233 | + |
| 234 | + ```scss |
| 235 | + .btn-green { |
| 236 | + background: green; |
| 237 | + font-weight: bold; |
| 238 | + // ... |
| 239 | + } |
| 240 | + ``` |
| 241 | + |
| 242 | +2. `@include` 声明 |
| 243 | + |
| 244 | + 紧随后面的是 `@include`,这样可以使得整个选择器的可读性更高。 |
| 245 | + |
| 246 | + ```scss |
| 247 | + .btn-green { |
| 248 | + background: green; |
| 249 | + font-weight: bold; |
| 250 | + @include transition(background 0.5s ease); |
| 251 | + // ... |
| 252 | + } |
| 253 | + ``` |
| 254 | + |
| 255 | +3. 嵌套选择器 |
| 256 | + |
| 257 | + _如果有必要_用到嵌套选择器,把它们放到最后,在规则声明和嵌套选择器之间要加上空白,相邻嵌套选择器之间也要加上空白。嵌套选择器中的内容也要遵循上述指引。 |
| 258 | + |
| 259 | + ```scss |
| 260 | + .btn { |
| 261 | + background: green; |
| 262 | + font-weight: bold; |
| 263 | + @include transition(background 0.5s ease); |
| 264 | + |
| 265 | + .icon { |
| 266 | + margin-right: 10px; |
| 267 | + } |
| 268 | + } |
| 269 | + ``` |
| 270 | + |
| 271 | +<a name="variables"></a> |
| 272 | +### 变量 |
| 273 | + |
| 274 | +变量名应使用破折号(例如 `$my-variable`)代替 camelCased 和 snake_cased 风格。对于仅用在当前文件的变量,可以在变量名之前添加下划线前缀(例如 `$_my-variable`)。 |
| 275 | + |
| 276 | +<a name="mixins"></a> |
| 277 | +### Mixins |
| 278 | + |
| 279 | +为了让代码遵循 DRY 原则(Don't Repeat Yourself)、增强清晰性或抽象化复杂性,应该使用 mixin,这与那些命名良好的函数的作用是异曲同工的。虽然 mixin 可以不接收参数,但要注意,假如你不压缩负载(比如通过 gzip),这样会导致最终的样式包含不必要的代码重复。 |
| 280 | + |
| 281 | +<a name="extend-directive"></a> |
| 282 | +### 扩展指令 |
| 283 | + |
| 284 | +应避免使用 `@extend` 指令,因为它并不直观,而且具有潜在风险,特别是用在嵌套选择器的时候。即便是在顶层占位符选择器使用扩展,如果选择器的顺序最终会改变,也可能会导致问题。(比如,如果它们存在于其他文件,而加载顺序发生了变化)。其实,使用 @extend 所获得的大部分优化效果,gzip 压缩已经帮助你做到了,因此你只需要通过 mixin 让样式表更符合 DRY 原则就足够了。 |
| 285 | + |
| 286 | +<a name="nested-selectors"></a> |
| 287 | +### 嵌套选择器 |
| 288 | + |
| 289 | +**请不要让嵌套选择器的深度超过 3 层!** |
| 290 | + |
| 291 | +```scss |
| 292 | +.page-container { |
| 293 | + .content { |
| 294 | + .profile { |
| 295 | + // STOP! |
| 296 | + } |
| 297 | + } |
| 298 | +} |
| 299 | +``` |
| 300 | + |
| 301 | +当遇到以上情况的时候,你也许是这样写 CSS 的: |
| 302 | + |
| 303 | +* 与 HTML 强耦合的(也是脆弱的)*—或者—* |
| 304 | +* 过于具体(强大)*—或者—* |
| 305 | +* 没有重用 |
| 306 | + |
| 307 | + |
| 308 | +再说一遍: **永远不要嵌套 ID 选择器!** |
| 309 | + |
| 310 | +如果你始终坚持要使用 ID 选择器(劝你三思),那也不应该嵌套它们。如果你正打算这么做,你需要先重新检查你的标签,或者指明原因。如果你想要写出风格良好的 HTML 和 CSS,你是**不**应该这样做的。 |
| 311 | + |
0 commit comments