CSS編碼風(fēng)格指南

CSS Guide

CSS編碼風(fēng)格指南。

文檔目錄

  1. 命名規(guī)范
  2. 代碼風(fēng)格
  3. 通用
  4. 值與單位
  5. 文本排版
  6. 變換與動(dòng)畫
  7. 媒體查詢
  8. 兼容性
  9. 代碼注釋

1 命名規(guī)范

該命名規(guī)范主要解決以下問題：

  • 從類名可以清晰區(qū)分出其功能作用，使頁面結(jié)構(gòu)清晰【命名空間、標(biāo)識(shí)符】；
  • 以組件、模塊的思想去寫一個(gè)區(qū)塊的結(jié)構(gòu)，強(qiáng)化結(jié)構(gòu)的模塊化【BEM模塊思想】；
  • 減少多人合作、項(xiàng)目耦合等情況下的命名沖突【命名空間】；

1.1 命名思想

項(xiàng)目如果沒使用樣式局部作用域框架（如vue），則使用BEM命名規(guī)則。

【強(qiáng)制】 區(qū)塊、模塊、組件等一個(gè)整個(gè)的結(jié)構(gòu)遵循BEM命名思想；

當(dāng)你能確定組件內(nèi)最后一級(jí)的結(jié)構(gòu)不會(huì)再發(fā)生變化時(shí)，最后一級(jí)可省略類名，使用兩層嵌套；

  • .block 代表了更高級(jí)別的抽象或組件；
  • .block__element 代表.block的后代，用于形成一個(gè)完整的.block的整體；
  • .is- | .has- | .ext- 代表.block的修飾符，不使用雙中劃線--。

相關(guān)鏈接：

1.2 多單詞連接

【強(qiáng)制】 用中劃線連接多個(gè)單詞，例如：news-list；

1.3 命名空間

【推薦】 在合適的地方使用命名空間；

  • 狀態(tài)：以is為命名空間，表示動(dòng)態(tài)的、具有交互性質(zhì)的狀態(tài)，例如：.is-open、.is-active、.is-selected 等；
  • 組件：以ui或者mod為命名空間，表示可復(fù)用、移植的組件模塊，例如：.ui-slider、.mod-drop-menu等；
  • 擴(kuò)展：以ext為命名空間，表示對(duì)組件基類的視覺形態(tài)的擴(kuò)展，例如：.ext-cover等；

1.4 區(qū)塊命名

【推薦】 一般區(qū)塊都可以劃分為頭部、身體和尾部，因此建議給你的區(qū)塊分別以 hd、bd、ft來劃分；

示例：

.ui-card__hd {
    margin: 0;
}

.ui-card__bd {
    margin: 0;
}

.ui-card__ft {
    margin: 0;
}

附：命名示例

[圖片上傳失敗...(image-bcddcf-1608025153993)]

2 代碼風(fēng)格

2.1 縮進(jìn)

【強(qiáng)制】 使用 2 個(gè)空格做為一個(gè)縮進(jìn)層級(jí)，不允許使用 4 個(gè)空格 或 tab 字符；

示例：

/* Not so great */
.selector {
  margin: 0;
}

/* Better */
.selector {
    margin: 0;
}

2.2 空格

【強(qiáng)制】 選擇器 與 {之間必須包含空格；

示例：

/* Not so great */
.selector{
}

/* Better */
.selector {
}

【強(qiáng)制】 >、+、~ 選擇器的兩邊各保留一個(gè)空格;

示例：

/* Not so great */
main>nav {
    padding: 10px;
}
label+input {
    margin-left: 5px;
}
input:checked~button {
    background-color: #69C;
}

/* Better */
main > nav {
    padding: 10px;
}
label + input {
    margin-left: 5px;
}
input:checked ~ button {
    background-color: #69C;
}

【強(qiáng)制】 屬性名 與之后的 : 之間不允許包含空格， :與 屬性值 之間必須包含空格；

示例：

/* Not so great */
margin :0;

/* Better */
margin: 0;

【強(qiáng)制】 列表型屬性值 書寫在單行時(shí)，,后必須跟一個(gè)空格；

示例：

/* Not so great */
font-family: Arial,sans-serif;
box-shadow: 0 0 2px rgba(0,128,0,.3);

/* Better */
font-family: Arial, sans-serif;
box-shadow: 0 0 2px rgba(0, 128, 0, .3);

2.3 選擇器

【強(qiáng)制】 當(dāng)一個(gè) rule 包含多個(gè) selector 時(shí)，每個(gè)選擇器聲明必須獨(dú)占一行；

示例：

/* Not so great */
.post, .page, .comment {
    line-height: 1.5;
}

/* Better */
.post,
.page,
.comment {
    line-height: 1.5;
}

2.4 屬性

【強(qiáng)制】 屬性定義必須另起一行；

示例：

/* Not so great */
.selector { margin: 0; padding: 0;}

/* Better */
.selector {
    margin: 0;
    padding: 0;
}

【強(qiáng)制】 屬性定義后必須以分號(hào)結(jié)尾；

示例：

/* Not so great */
.selector {
    margin: 0
}

/* Better */
.selector {
    margin: 0;
}

3. 通用

3.1 選擇器

【強(qiáng)制】 如無必要，不得為id、class選擇器添加 類型選擇器 進(jìn)行限定；

在性能和維護(hù)性上，都有一定的影響。

示例：

/* Not so great */
dialog#error,
p.danger-message {
    font-color: #c00;
}

/* Better */
#error,
.danger-message {
    font-color: #c00;
}

【建議】 選擇器的嵌套層級(jí)應(yīng)該不大于 3 級(jí)，位置靠后的限定條件應(yīng)可能精確；

在性能和維護(hù)性上，都有一定的影響。

示例：

/* Not so great */
.comment ul li a span {}
#top-hero .hero-avatar li.avatar .pic em {}

/* Better */
.comment .date {}
#top-hero .pic em {}

3.2 屬性

3.2.1 屬性書寫順序

【建議】 同一 rule set 下的屬性在書寫時(shí)，應(yīng)按功能進(jìn)行分組，并以 Formatting Model > Box Model > Typographic > Visual 的順序書寫，以提高代碼的可讀性。

  1. Positioning Model 布局方式、位置；相關(guān)屬性包括：position / top / right / bottom / left / z-index / display / float / ...
  2. Box model 盒模型；相關(guān)屬性包括：width / height / padding / margin / border / overflow / ...
  3. Typographic 文本排版；相關(guān)屬性包括：font / line-height / text-align / word-wrap / ...
  4. Visual 視覺外觀；相關(guān)屬性包括：color / background / list-style / transform / animation / transition / ...
  5. 如果包含 content 屬性，應(yīng)放在最前面；

Positioning 處在第一位，因?yàn)樗梢允挂粋€(gè)元素脫離正常文本流，并且覆蓋盒模型相關(guān)的樣式。盒模型緊跟其后，因?yàn)樗麤Q定了一個(gè)組件的大小和位置。其他屬性只在組件 內(nèi)部 起作用或者不會(huì)對(duì)前面兩種情況的結(jié)果產(chǎn)生影響，所以他們排在后面。

詳情資料 Twitter的strictPropertyOrder

3.2.2 屬性引號(hào)

【強(qiáng)制】 屬性選擇器中的值必須用雙引號(hào)包圍。不允許使用單引號(hào)，不允許不使用引號(hào)。

示例：

/* Not so great */
article[character='juliet'] {
    voice-family: "Vivien Leigh", victoria, female
}

/* Better */
article[character="juliet"] {
    voice-family: "Vivien Leigh", victoria, female
}

3.2.3 屬性簡(jiǎn)寫

簡(jiǎn)寫形式可以在一定程度上壓縮樣式，但并不意味著你可以對(duì)所有可以簡(jiǎn)寫的屬性聲明都使用簡(jiǎn)寫。過度使用簡(jiǎn)寫形式的屬性聲明會(huì)導(dǎo)致代碼混亂，會(huì)對(duì)屬性值帶來不必要的覆蓋從而引起意外的副作用，并且不能充分利用CSS的繼承。常見的濫用簡(jiǎn)寫屬性聲明的情況如下：

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

如果你只需定義其中的一兩個(gè)屬性，而不是全部，盡量分開來寫：

/* Better */
.selector {
    margin-bottom: 10px;
    background-color: red;
    background-image: url(image.jpg);
    border-top-left-radius: 3px;
    border-top-right-radius: 3px;
}

/* Not so great */
.selector {
    margin: 0 0 10px;
    background: red;
    background: url(image.jpg);
    border-radius: 3px 3px 0 0;
}

4 值與單位

4.1 文本

【強(qiáng)制】 文本內(nèi)容必須用雙引號(hào)包圍，不允許使用單引號(hào)；

文本類型的內(nèi)容可能在選擇器、屬性值等內(nèi)容中。

示例：

/* Not so great */
html[lang|=zh] q:before {
    font-family: 'Microsoft YaHei', sans-serif;
    content: '“';
}

/* Better */
html[lang|="zh"] q:after {
    font-family: "Microsoft YaHei", sans-serif;
    content: "“";
}

4.2 數(shù)值

【強(qiáng)制】 當(dāng)數(shù)值為 0 - 1 之間的小數(shù)時(shí)，省略整數(shù)部分的 0；

示例：

/* Not so great */
.selector {
    opacity: 0.8;
}

/* Better */
.selector {
    opacity: .8;
}

4.3 長(zhǎng)度

【強(qiáng)制】 長(zhǎng)度為 0 時(shí)須省略單位 (也只有長(zhǎng)度單位可省)；

示例：

/* Not so great */
.selector {
    margin: 0px 10px;
}

/* Better */
.selector {
    margin: 0 10px;
}

4.4 url()

【強(qiáng)制】 url() 函數(shù)中的路徑不加引號(hào)；

示例：

/* Not so great */
.selector {
    background: url("bg.png");
}

/* Better */
.selector {
    background: url(bg.png);
}

4.5 顏色

【強(qiáng)制】 RGB顏色值必須使用十六進(jìn)制記號(hào)形式 #rrggbb，不允許使用 rgb()，帶有alpha的顏色信息可以使用 rgba()；顏色值不允許使用命名色值；

示例：

/* Not so great */
.selector {
    box-shadow: 0 0 2px rgba(0,128,0,.3);
    border-color: rgb(0, 128, 0);
    color: gray;
}

/* Better */
.selector {
    box-shadow: 0 0 2px rgba(0, 128, 0, .3);
    border-color: #008000;
    color: #999;
}

【建議】 顏色值中的英文字符采用小寫，至少要保證同一項(xiàng)目?jī)?nèi)一致；

示例：

/* Not so great */
.selector {
    color: #0073AA;
}

/* Better */
.selector {
    color: #0073aa;
}

4.6 2D位置

【強(qiáng)制】 必須同時(shí)給出水平和垂直方向的位置；

2D 位置初始值為 0% 0%，但在只有一個(gè)方向的值時(shí)，另一個(gè)方向的值會(huì)被解析為 center。為避免理解上的困擾，應(yīng)同時(shí)給出兩個(gè)方向的值。 background-position屬性值的定義

示例：

/* Not so great */
.selector {
    background-position: top; /* 50% 0% */
}

/* Better */
.selector {
    background-position: center top; /* 50% 0% */
}

5. 文本排版

5.1 字體族

【強(qiáng)制】 font-family 屬性中的字體族名稱應(yīng)使用字體的英文 Family Name，其中如有空格，須放置在引號(hào)中；

常見的字體族名稱如下：

字體 操作系統(tǒng) Family Name
宋體 (中易宋體) Windows SimSun
黑體 (中易黑體) Windows SimHei
微軟雅黑 Windows Microsoft YaHei
微軟正黑 Windows Microsoft JhengHei
華文黑體 Mac/iOS STHeiti
冬青黑體 Mac/iOS Hiragino Sans GB
文泉驛正黑 Linux WenQuanYi Zen Hei
文泉驛微米黑 Linux WenQuanYi Micro Hei

【強(qiáng)制】 font-family 應(yīng)當(dāng)遵循以下順序：

  1. 西文字體在前，中文字體在后；
  2. 效果佳 (質(zhì)量高/更能滿足需求) 的字體在前，效果一般的字體在后的順序編寫；
  3. 最后必須指定一個(gè)通用字體族( serif / sans-serif )；

詳細(xì)說明可參考 如何保證網(wǎng)頁的字體在各平臺(tái)都盡量顯示為最高質(zhì)量的黑體？

【強(qiáng)制】 font-family 不區(qū)分大小寫，但在同一個(gè)項(xiàng)目中，同樣的 Family Name 大小寫必須統(tǒng)一；

示例：

/* Not so great */
body {
    font-family: arial, sans-serif;
}

h1 {
    font-family: Arial, "Microsoft YaHei", sans-serif;
}

/* Better */
body {
    font-family: Arial, sans-serif;
}

h1 {
    font-family: Arial, "Microsoft YaHei", sans-serif;
}

5.2 字重

【強(qiáng)制】 font-weight 屬性必須使用數(shù)值方式描述；

CSS 的字重分 100 – 900 共九檔，但目前受字體本身質(zhì)量和瀏覽器的限制，實(shí)際上支持 400 和 700 兩檔，分別等價(jià)于關(guān)鍵詞 normal 和 bold。

瀏覽器本身使用一系列啟發(fā)式規(guī)則來進(jìn)行匹配，在 >700 時(shí)一般匹配字體的 Regular 字重，>=700 時(shí)匹配 Bold 字重。

但已有瀏覽器開始支持 =600 時(shí)匹配 Semibold 字重 (見此表)，故使用數(shù)值描述增加了靈活性，也更簡(jiǎn)短。

示例：

/* Not so great */
.selector {
    font-weight: bold;
}

/* Better */
.selector {
    font-weight: 700;
}

6 變換與動(dòng)畫

【強(qiáng)制】 使用 transition 定義屬性時(shí)應(yīng)遵循以下順序：

  1. [ transition-property ]：檢索或設(shè)置對(duì)象中的參與過渡的屬性；
  2. [ transition-duration ]：檢索或設(shè)置對(duì)象過渡的持續(xù)時(shí)間；
  3. [ transition-timing-function ]：檢索或設(shè)置對(duì)象中過渡的動(dòng)畫類型；
  4. [ transition-delay ]：檢索或設(shè)置對(duì)象延遲過渡的時(shí)間；

transition：[ transition-property ] || [ transition-duration ] || [ transition-timing-function ] || [ transition-delay ]

如果順序錯(cuò)亂，在某些安卓瀏覽器上會(huì)讓動(dòng)畫失效。

示例：

/* Not so great */
.selector {
    transition: color .2s 0 ease-in;
}

/* Better */
.selector {
    transition: color .2s ease-in 0;
}

【建議】 盡可能在瀏覽器能高效實(shí)現(xiàn)的屬性上添加過渡和動(dòng)畫：

在可能的情況下應(yīng)選擇這樣四種變換：

  • transform: translate(npx, npx);
  • transform: scale(n);
  • transform: rotate(ndeg);
  • opacity: 0..1;

詳見 High Performance Animations

7 媒體查詢

【強(qiáng)制】 Media Query 不得單獨(dú)編排，必須與相關(guān)的規(guī)則一起定義；

不要將他們一起放到一個(gè)獨(dú)立的樣式文件中，或者丟在文檔的最底部，這樣做只會(huì)讓大家以后更容易忘記他們。

示例：

/* Not so great */
/* header styles */
/* main styles */
/* footer styles */

@media (...) {
    /* header styles */
    /* main styles */
    /* footer styles */
}

/* Better */
/* header styles */
@media (...) {
    /* header styles */
}

/* main styles */
@media (...) {
    /* main styles */
}

/* footer styles */
@media (...) {
    /* footer styles */
}

8 兼容性

8.1 屬性前綴

【強(qiáng)制】 帶私有前綴的屬性由長(zhǎng)到短排列，按冒號(hào)位置對(duì)齊；

標(biāo)準(zhǔn)屬性放在最后，按冒號(hào)對(duì)齊方便閱讀與編輯。

示例：

/* Not so great */
.selector {
    transition: color .2s ease-in 0;
    -webkit-transition: color .2s ease-in 0;
    -moz-transition: color .2s ease-in 0;
}

/* Better */
.selector {
    -webkit-transition: color .2s ease-in 0;
       -moz-transition: color .2s ease-in 0;
            transition: color .2s ease-in 0;
}

8.2 hack

【建議】 如果有其他解決方案，請(qǐng)不要使用hack；

9 代碼注釋

代碼是由人編寫并維護(hù)的。請(qǐng)確保你的代碼能夠自描述、注釋良好并且易于他人理解。好的代碼注釋能夠傳達(dá)上下文關(guān)系和代碼目的。不要簡(jiǎn)單地重申組件或 class 名稱。

9.1 單行注釋

【強(qiáng)制】 星號(hào)與內(nèi)容之間必須保留一個(gè)空格；

示例：

/* 新聞中心表格隔行變色 */

9.2 多行注釋

【強(qiáng)制】 星號(hào)要一列對(duì)齊，星號(hào)與內(nèi)容之間必須保留一個(gè)空格；

示例：

/**
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

9.3 文件注釋

【強(qiáng)制】 文件頂部必須包含文件注釋，用 @file 標(biāo)識(shí)文件說明。星號(hào)要一列對(duì)齊，星號(hào)與內(nèi)容之間必須保留一個(gè)空格，標(biāo)識(shí)符冒號(hào)與內(nèi)容之間必須保留一個(gè)空格；

/**
 * @file: 文件概要描述
 * @author: author-name(mail-name@domain.com)
 *          author-name2(mail-name2@domain.com)
 * @update: 2015-04-29 00:02:45
 */
  • @update為可選項(xiàng)，建議每次改動(dòng)都更新一下；
  • 當(dāng)該業(yè)務(wù)項(xiàng)目主要由固定的一個(gè)或多個(gè)人負(fù)責(zé)時(shí)，需要添加@author標(biāo)識(shí)，一方面是尊重勞動(dòng)成果，另一方面方便在需要時(shí)快速定位責(zé)任人；

參考資料：

  1. bootcss編碼規(guī)范
  2. 豆瓣CSS Code Guideline
  3. spec css style guide
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容