Skip to content

Commit 5774213

Browse files
committed
更新
1 parent 5854876 commit 5774213

File tree

1 file changed

+309
-1
lines changed

1 file changed

+309
-1
lines changed

README.md

Lines changed: 309 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,311 @@
11
# css-style-guide
22

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

Comments
 (0)