#CSS編碼標準 像任何編碼標準一樣，WordPress CSS編碼標準的目的是在WordPress開源項目和社區的各個方面，從核心代碼到主題到插件，創建一個基準。 項目中的文件應該顯示為由單個實體創建。 最重要的是，創建可讀，有意義，一致和美觀的代碼。 在核心樣式表中，通常會發現不一致。 我們正在努力解決這些問題，并盡一切努力從這一點開始補丁并提出遵循CSS編碼標準。 有關上述的更多信息和對UI /前端開發的貢獻將在一套單獨的指南中提出。 ## 結構 有很多不同的方法來構造樣式表。 以CSS為核心，重要的是要保持高度的可讀性。 這使得后續的貢獻者能夠清楚地了解文檔的流程。 - 使用制表符，而不是空格來縮進每個屬性。 - 在段之間添加兩條空白行，并在段中添加一行空白行。 - 每個選擇器應該在自己的行上，以逗號或開放的大括號結尾。 屬性值對應該在自己的行上，一個縮進的選項卡和一個結尾的分號。 關閉支架應該向左齊平，使用與打開選擇器相同的縮進水平。 **正確:** ```css #selector-1, #selector-2, #selector-3 { background: #fff; color: #000; } ``` **不正確** ```css #selector-1, #selector-2, #selector-3 { background: #fff; color: #000; } #selector-1 { background: #fff; color: #000; } ``` ## 選擇器 具有特殊性，承擔著很大的責任。 廣泛的選擇器使我們能夠高效，但如果沒有測試可能會產生不利后果。 特定于位置的選擇器可以節省時間，但會很快導致雜亂的樣式表。 做出最好的判斷，創建選擇器，在DOM的整體風格和布局之間找到適當的平衡。 - 類似于用于文件名的WordPress PHP編碼標準，在命名選擇器時使用帶有連字符的小寫和單獨的單詞。 避免使用駝峰命名和下劃線。 - 使用人類可讀選擇器來描述他們的風格。 - 屬性選擇器應該圍繞值使用雙引號 - 避免使用組合的選擇器，div.container可以簡單地表示為.container **正確：** ```css #comment-form { margin: 1em 0; } input[type="text"] { line-height: 1.1; } ``` **不正確** ```css #commentForm { /* 避免使用駝峰命名 */ margin: 0; } #comment_form { /* 避免下劃線。 */ margin: 0; } div#comment_form { /* 避免使用組合的選擇器。 */ margin: 0; } #c1-xr { /* 使用更好的名字。 */ margin: 0; } input[type=text] { /* 屬性選擇器應該圍繞值使用雙引號 */ line-height: 110% /* Also doubly incorrect */ } ``` ## 屬性 類似于選擇器，太具體的屬性將阻礙設計的靈活性。 少即是多。 確保您不會重復造型或引入固定尺寸（當液體溶液更可接受時）。 - 屬性后面應該有一個冒號和一個空格。 - 除字體名稱和供應商特定屬性外，所有屬性和值都應為小寫。 - 對于顏色使用十六進制代碼，如果需要透明度，則使用rgba（）。 避免RGB格式和大寫字母，并盡可能縮短值：#fff而不是#FFFFFF。 - 盡可能使用縮寫（除了覆蓋樣式）的背景，邊框，字體，列表樣式，邊距和填充值。 （有關速記參考，請參閱CSS速記。） **正確：** ```css #selector-1 { background: #fff; display: block; margin: 0; margin-left: 20px; } ``` **不正確:** ```css #selector-1 { background:#FFFFFF; display: BLOCK; margin-left: 20PX; margin: 0; } ``` ## 屬性排序 最重要的是，以某種方式選擇對您有意義的內容和語義。隨機排序是混亂，不是詩歌。在WordPress Core中，我們的選擇是邏輯或分組排序，其中屬性按意義進行分組，并在這些組內特別排序。組內的屬性也有策略地排序，以在節之間創建轉換，例如直接在顏色之前的背景。訂購的基準是： - 顯示 - 定位 - 盒子模型 - 顏色和排版 - 其他 >[info] 核心本身尚未使用的內容（例如CSS3動畫）可能沒有上述規定的位置，但可能以合乎邏輯的方式適合上述之一。正如CSS正在發展，所以我們的標準將會隨之發展。 - top/right/buttom/left（TRBL /故障）應該是任何相關屬性（例如邊距）的順序，就像順序在值中一樣。拐角說明符（例如border-radius - * - *）應該是左上，右上，右下，左下角。這來自于如何訂購速記值。 **示例:** ```css #overlay { position: absolute; z-index: 1; padding: 10px; background: #fff; color: #777; } ``` 經常使用的另一種方法，包括Automattic / WordPress.com主題小組，是按字母順序排列屬性，有或沒有某些例外。 **示例:** ```css #overlay { background: #fff; color: #777; padding: 10px; position: absolute; z-index: 1; } ``` ## 瀏覽器前綴 我們使用Autoprefixer作為預提交工具來輕松管理必要的瀏覽器前綴，從而使本部分的大部分成為可能。 對于沒有使用Grunt感興趣的用戶，瀏覽器前綴應該最長（-webkit-）到最短（未修改）。 所有其他間距依照其余標準。 ```css .sample-output { -webkit-box-shadow: inset 0 0 1px 1px #eee; -moz-box-shadow: inset 0 0 1px 1px #eee; box-shadow: inset 0 0 1px 1px #eee; } ``` ## 屬性的值 有許多方法可以輸入屬性的值。遵循以下準則，幫助我們保持高度的一致性。 - 空格之前的值，冒號后 - 不要用空格填寫圓括號 - 總是以分號結尾 - 使用雙引號而不是單引號，只有在需要時，例如當字體名稱有空格時。 - 應使用數值來定義字體權重（例如，400而不是正常值，而不是粗體）。 - 除非必要，否則0值不應有單位，例如具有過渡持續時間。 - 線高度也應該是無單位的，除非有必要將其定義為特定的像素值。這不僅僅是一個風格的慣例，但值得一提的是這里。更多信息：http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/ - 對于十進制值使用前導零，包括在rgba（）中。 - 一個屬性的多個逗號分隔值應由空格或換行符（包括rgba（））分隔開。換行符應用于較長的多部分值，例如速寫屬性（如box-shadow和text-shadow）。然后，第一個之后的每個后續值應該在新行上，縮進到與選擇器相同的級別，然后間隔到左上與先前的值對齊。 **正確：** ```css .class { /* Correct usage of quotes */ background-image: url(images/bg.png); font-family: "Helvetica Neue", sans-serif; font-weight: 700; } .class { /* Correct usage of zero values */ font-family: Georgia, serif; text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.5), 0 1px 0 #fff; } ``` **不正確:** ```css .class { /* Avoid missing space and semicolon */ background:#fff } .class { /* Avoid adding a unit on a zero value */ margin: 0px 0px 20px 0px; } .class { font-family: Times New Roman, serif; /* Quote font names when required */ font-weight: bold; /* Avoid named font weights */ } ``` ## 媒體查詢 媒體查詢允許我們優化降低不同屏幕大小的DOM。 如果您正在添加任何內容，請務必在您所針對的突破點上方和下方進行測試。 通常建議將媒體按媒體分組保存在樣式表的底部。 對于核心中的wp-admin.css文件是一個例外，因為它非常大，每個部分基本上都代表自己的樣式表。 因此，介質查詢在適用的部分底部添加。 媒體查詢的規則集應該縮進一級。 **例：** ```css @media all and (max-width: 699px) and (min-width: 520px) { /* Your selectors */ } ``` ## 注釋 注釋和評論自由。 如果有關于文件大小的問題，請使用最小化的文件和SCRIPT_DEBUG常量。 長注釋應手動將行長度分為80個字符。 - 應將目錄用于更長的樣式表，特別是高分段的樣式表。 使用索引號（1.0,1.1,2.0等）有助于搜索和跳轉到某個位置。 - 注釋應該像PHPDoc一樣格式化。 CSSDoc標準不一定被廣泛接受或使用，但其一些方面可能會隨時間推移。 Section / subsection標題應該在前后有換行符。 內聯注釋不應該有空的換行符，將注釋與它所涉及的項目分開。 **示例:** ```css /** * #.# Section title * * Description of section, whether or not it has media queries, etc. */ .selector { float: left; } ``` **行內:** ```css /* This is a comment about this selector */ .another-selector { position: absolute; top: 0 !important; /* I should explain why this is so !important */ } ``` ## 最佳實踐 樣式表往往長度很長。 焦點慢慢失去，而預期的目標開始重復和重疊。 從一開始就編寫智能代碼有助于我們保留概述，同時在變化中保持靈活性。 - 如果您嘗試解決問題，請嘗試在添加更多代碼之前刪除代碼。 - 魔法數字是不幸的。 這些是一次性用作快速修復的數字。 示例：`.box {margin-top：37px}`。 - DOM會隨著時間的推移而改變，將目標要使用的元素，而不是通過其父母“找到它”。 示例：在元素上使用`.highlight`，而不是`.highlight a`（選擇器在父項上） - 知道何時使用`height`屬性。 當您包含外部元素（如圖像）時，應使用它。 否則使用`line-height`可以獲得更大的靈活性。 - 不要重新設置默認屬性和值組合（例如，顯示：塊;塊級元素）。 # 編寫如一、符合習慣的CSS的原則 以下文檔將概述一個合理的CSS開發風格指導。本指導文件強烈鼓勵開發者使用已經存在了的、常見的、合力的文風。您應該有選擇地吸納一些內容來創造您自己的風格指南。 ## 1. 通用原則 > “作為成功的項目的一員，很重要的一點是意識到只為自己寫代碼是很糟糕的行為。如果將有成千上萬人使用你的代碼， > 那么你需要編寫最具明確性的代碼，而不是以自我的喜好來彰顯自己的智商。” - Idan Gazit * 別想著過早地優化代碼。先得保證它們可讀又可理解才行。 * 在任何代碼庫中，無論有多少人參與及貢獻，所有代碼都應該如同一個人編寫的一樣。 * 嚴格執行一致認可的風格。 * 如果有疑議，則使用現有的、通用的模式。 ## 2. 空格 在項目的所有代碼中，應該只有一個風格。在空格的使用上，必須始終保持一致。使用空格來提高可讀性。 * *永遠不要*在縮進時混用空格和制表符（又稱TAB符號）。 * 在軟縮進（使用空格）和真正的制表符間選擇其一，并始終堅持這一選擇。（推薦使用空格） * 如果使用空格進行縮進，選擇每個縮進所使用的空格數。（推薦：4個空格） 提示：將編輯器配置為“顯示不可見內容”。這使你可以清除行尾的空格和不需要縮進的空行里的空格，同時可以避免對注釋的污染。 提示：確定好一種空格格式后，您可以用一個[EditorConfig](http://editorconfig.org/)文件（或者其他相同的東西）來幫助在代碼庫之間維持這種基本的空格約定。 ## 3. 注釋 良好的注釋是非常重要的。請留出時間來描述組件（component）的工作方式、局限性和構建它們的方法。不要讓你的團隊其它成員 來猜測一段不通用或不明顯的代碼的目的。 注釋的風格應當簡潔，并在代碼庫中保持統一。 * 將注釋放在主題上方并獨占一行。 * 控制每行長度在合理的范圍內，比如80個字符。 * 使用注釋從字面上將CSS代碼分隔為獨立的部分。 * 注釋的大小寫應當與普通句子相同，并且使用一致的文本縮進。 提示：通過配置編輯器，可以提供快捷鍵來輸出一致認可的注釋模式。 #### CSS示例： ```css /* ========================================================================== 區塊代碼注釋 ========================================================================== */ /* 次級區塊代碼注釋 ========================================================================== */ /** * “Doxygen式注釋格式”的簡短介紹 * * 較長的說明文本從這里開始，這是這段文字的第一句話，而且這句話還 * 沒結束，過了好一會兒，我了個去終于結束了，煩不煩啊。 * * 當需要進行更細致的解釋說明、提供文檔文本時，較長的說明文本就很 * 有用了。這種長長的說明文本，可以包括示例HTML啦、鏈接啦等等其 * 他你認為重要或者有用的東西。 * * @tag 這是一個叫做“tag”的標簽。 * * TODO: 這個“‘需做’陳述”描述了一個接下來要去做的小工作。這種文本， * 如果超長了的話，應該在80個半角字符（如英文）或40個全角字符（ * 如中文）后便換行，并（在“ * ”的基礎上）再在后面縮進兩個空格。 */ /* 一般的注釋 */ ``` <a name="format"></a> ## 4. 格式 最終選擇的代碼風格必須保證：易于閱讀，易于清晰地注釋，最小化無意中引入錯誤的可能性，可生成有用的diff和blame。 1. 在多個選擇器的規則集中，每個單獨的選擇器獨占一行。 2. 在規則集的左大括號前保留一個空格。 3. 在聲明塊中，每個聲明獨占一行。 4. 每個聲明前保留一級縮進。 5. 每個聲明的冒號后保留一個空格。 6. 對于聲明塊的最后一個聲明，始終保留結束的分號。 7. 規則集的右大括號保持與該規則集的第一個字符在同一列。 8. 每個規則集之間保留一個空行。 ```css .selector-1, .selector-2, .selector-3[type="text"] { -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box; display: block; font-family: helvetica, arial, sans-serif; color: #333; background: #fff; background: linear-gradient(#fff, rgba(0, 0, 0, 0.8)); } .selector-a, .selector-b { padding: 10px; } ``` #### 聲明順序 樣式聲明的順序應當遵守一個單一的原則。我的傾向是將相關的屬性組合在一起，并且將對結構來說比較重要的屬性（如定位或者盒模型） 放在前面，先于排版、背景及顏色等屬性。 小型的開發團體，可能會想要把相關的屬性聲明（比如說定位和箱模型）擺在一起。 ```css .selector { /* Positioning */ position: absolute; z-index: 10; top: 0; right: 0; bottom: 0; left: 0; /* Display & Box Model */ display: inline-block; overflow: hidden; box-sizing: border-box; width: 100px; height: 100px; padding: 10px; border: 10px solid #333; margin: 10px; /* Other */ background: #000; color: #fff; font-family: sans-serif; font-size: 16px; text-align: right; } ``` 大型團隊，則可能更喜歡按字母排序，因為這樣做起來很方便，而且維護起來很容易。 #### 例外及細微偏移原則的情況 對于大量僅包含單條聲明的聲明塊，可以使用一種略微不同的單行格式。在這種情況下，在左大括號之后及右大括號之前都應該保留一個空格。 ```css .selector-1 { width: 10%; } .selector-2 { width: 20%; } .selector-3 { width: 30%; } ``` 對于以逗號分隔并且非常長的屬性值 -- 例如一堆漸變或者陰影的聲明 -- 可以放在多行中，這有助于提高可讀性，并易于生成有效的diff。這種情況下有多 種格式可以選擇，以下展示了一種格式。 ```css .selector { box-shadow: 1px 1px 1px #000, 2px 2px 1px 1px #ccc inset; background-image: linear-gradient(#fff, #ccc), linear-gradient(#f3c, #4ec); } ``` #### 雜項 * 在十六進制值中，使用小寫，如`#aaa`。 * 單引號或雙引號的選擇保持一致。推薦使用雙引號，如`content: ""`。 * 對于選擇器中的屬性值也加上引號，如`input[type="checkbox"]`。 * *如果可以的話*，不要給0加上單位, 如`margin: 0`。 ### 預處理：格式方面額外的考慮 不同的CSS預處理有著不同的特性、功能以及語法。編碼習慣應當根據使用的預處理程序進行擴展，以適應其特有的功能。推薦在使用SCSS時遵守以下指導。 * 將嵌套深度限制在1級。對于超過2級的嵌套，給予重新評估。這可以避免出現過于詳實的CSS選擇器。 * 避免大量的嵌套規則。當可讀性受到影響時，將之打斷。推薦避免出現多于20行的嵌套規則出現。 * 始終將`@extend`語句放在聲明塊的第一行。 * 如果可以的話，將`@include`語句放在聲明塊的頂部，緊接著`@extend`語句的位置。 * 考慮在自定義函數的名字前加上`x-`或其它形式的前綴。這有助于避免將自己的函數和CSS的原生函數混淆，或函數命名與庫函數沖突。 ```scss .selector-1 { @extend .other-rule; @include clearfix(); @include box-sizing(border-box); width: x-grid-unit(1); // other declarations } ``` <a name="naming"></a> ## 5. 命名 不要試著把自己當作編譯器或者預處理器，因此命名的時候盡量采用清晰的、有意義的名字。另外，對于 html文件和css文件中的代碼，盡量采用一致的命名規則。 ```css /* 沒有意義的命名 */ .s-scr { overflow: auto; } .cb { background: #000; } /* 比較有意義的命名方式 */ .is-scrollable { overflow: auto; } .column-body { background: #000; } ``` <a name="example"></a> ## 6. 實例 下面是含有上述約定的示例代碼： ```css /* ========================================================================== Grid layout ========================================================================== */ /** * Column layout with horizontal scroll. * * This creates a single row of full-height, non-wrapping columns that can * be browsed horizontally within their parent. * * Example HTML: * * <div class="grid"> * <div class="cell cell-3"></div> * <div class="cell cell-3"></div> * <div class="cell cell-3"></div> * </div> */ /** * Grid container * * Must only contain `.cell` children. * * 1. Remove inter-cell whitespace * 2. Prevent inline-block cells wrapping */ .grid { height: 100%; font-size: 0; /* 1 */ white-space: nowrap; /* 2 */ } /** * Grid cells * * No explicit width by default. Extend with `.cell-n` classes. * * 1. Set the inter-cell spacing * 2. Reset white-space inherited from `.grid` * 3. Reset font-size inherited from `.grid` */ .cell { position: relative; display: inline-block; overflow: hidden; box-sizing: border-box; height: 100%; padding: 0 10px; /* 1 */ border: 2px solid #333; vertical-align: top; white-space: normal; /* 2 */ font-size: 16px; /* 3 */ } /* Cell states */ .cell.is-animating { background-color: #fffdec; } /* Cell dimensions ========================================================================== */ .cell-1 { width: 10%; } .cell-2 { width: 20%; } .cell-3 { width: 30%; } .cell-4 { width: 40%; } .cell-5 { width: 50%; } /* Cell modifiers ========================================================================== */ .cell--detail, .cell--important { border-width: 4px; } ``` <a name="organization"></a> ## 7. 代碼組織 對于css代碼庫來說，如何組織代碼文件是很重要的，尤其對于那些很大的代碼庫顯得更加重要。這里介紹 幾個組織代碼的建議： * 邏輯上對不同的代碼進行分離。 * 不同的組件(component)的css盡量用不同的css文件（可以在build階段用工具合并到一起） * 如果用到了預處理器（比如less），把一些公共的樣式代碼抽象成變量，例如顏色，字體等等。 <a name="build-and-deployment"></a> ## 8. 構建及部署 任何一個項目，都應該有一個build的過程，在這個階段我們可以通過工具對代碼進行檢測，測試，壓縮等等，還 可以為生產環境準備好帶有版本號的代碼。在這里我推薦一下[grunt](https://github.com/cowboy/grunt)這個工具，我感覺它很不錯。 <a name="acknowledgements"></a> ## 致謝 感謝所有對[idiomatic.js](https://github.com/rwldrn/idiomatic.js)作出貢獻的網友。 ##許可 _Principles of writing consistent, idiomatic CSS_ 是Nicolas Gallagher發布在[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/)許可證下的作品。該許可證適用于本代碼棧中的所有文檔，包括翻譯文本。 本作品基于[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css)著就。