SCSS style guide · Gitlab 中文文檔

# SCSS style guide > 原文：[https://docs.gitlab.com/ee/development/fe_guide/style/scss.html](https://docs.gitlab.com/ee/development/fe_guide/style/scss.html) * [Rules](#rules) * [Utility Classes](#utility-classes) * [Where are utility classes defined?](#where-are-utility-classes-defined) * [Where should I put new utility classes?](#where-should-i-put-new-utility-classes) * [When should I create component classes?](#when-should-i-create-component-classes) * [Naming](#naming) * [Formatting](#formatting) * [Colors](#colors) * [Indentation](#indentation) * [Semicolons](#semicolons) * [Shorthand](#shorthand) * [Zero Units](#zero-units) * [Selectors with a `js-` Prefix](#selectors-with-a-js--prefix) * [IDs](#ids) * [Variables](#variables) * [Linting](#linting) * [Fixing issues](#fixing-issues) * [Ignoring issues](#ignoring-issues) # SCSS style guide[](#scss-style-guide "Permalink") 本樣式指南為 SCSS 推薦了最佳做法，以使樣式易于閱讀，易于維護并為最終用戶提供高性能. ## Rules[](#rules "Permalink") 我們的 CSS 是現有方法和舊方法的結合. 這意味著有時可能難以按照本指南進行操作. 這意味著您肯定會遇到例外，在這種情況下，如果不付出巨大的努力，很難甚至不可能遵循該指南. 在這種情況下，您可以與審核者和維護者一起確定不符合這些規則的方法. 請努力限制這些情況. ### Utility Classes[](#utility-classes "Permalink") 為了減少隨著站點的增加而產生更多 CSS 的可能性，與添加新 CSS 相比，更喜歡使用實用程序類. 在復雜的情況下，可以通過添加組件類來解決 CSS. #### Where are utility classes defined?[](#where-are-utility-classes-defined "Permalink") 優先使用[在 GitLab UI 中定義](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/css.md#utilities)的[實用程序類](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/css.md#utilities) . [在 Unpkg 上](https://unpkg.com/browse/@gitlab/ui/src/scss/utilities.scss)也可以[看到](https://unpkg.com/browse/@gitlab/ui/src/scss/utilities.scss)一個簡單的類列表. 在類[`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/utilities.scss)和[`common.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/framework/common.scss)被棄用. 應該避免使用[`common.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/framework/common.scss)中的非設計系統值的類，而采用一致的值. Avoid [Bootstrap’s Utility Classes](https://s0getbootstrap0com.icopy.site/docs/4.3/utilities/). #### Where should I put new utility classes?[](#where-should-i-put-new-utility-classes "Permalink") 如果尚未將所需的類添加到 GitLab UI，則可以添加它！請遵循[實用程序文件中](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/master/src/scss/utility-mixins)記錄的命名模式，并參閱[GitLab UI 的 CSS 文檔](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/contributing/adding_css.md#adding-utility-mixins)以獲取更多詳細信息，尤其是有關添加響應式和有狀態規則的信息. 如果它是不可能等待 GitLab UI 更新（通常一天），將該類添加到[`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/utilities.scss)按照 GitLab UI 文件相同的命名約定. 應該解決將類反向移植到 GitLab UI 并將其從 GitLab 中刪除的后續問題. #### When should I create component classes?[](#when-should-i-create-component-classes "Permalink") 我們建議采用"效用至上"的方法. 1. 從實用程序類開始. 2. 如果將實用程序類組合到組件類中可以消除代碼重復并封裝明確的職責，請執行此操作. 這鼓勵了組件類的有機增長，并防止創建一次性不可重用的類. 而且，從"效用優先"產生的類的種類傾向于以設計為中心（例如`.button` ， `.alert` ， `.card` ）而不是以領域為中心（例如`.security-report-widget` ， `.commit-header-icon` ）. 使用"效用優先"創建的組件類的示例包括： * [`.circle-icon-container`](https://gitlab.com/gitlab-org/gitlab/blob/579fa8b8ec7eb38d40c96521f517c9dab8c3b97a/app/assets/stylesheets/framework/icons.scss#L85) * [`.d-flex-center`](https://gitlab.com/gitlab-org/gitlab/blob/900083d89cd6af391d26ab7922b3f64fa2839bef/app/assets/stylesheets/framework/common.scss#L425) Inspiration: * [https://tailwindcss.com/docs/utility-first/](https://tailwindcss.com/docs/utility-first/) * [https://tailwindcss.com/docs/extracting-components/](https://tailwindcss.com/docs/extracting-components/) ### Naming[](#naming "Permalink") 文件名應使用`snake_case` . CSS 類應使用`lowercase-hyphenated`格式，而不是`snake_case`或`camelCase` . ``` // Bad .class_name { color: #fff; } // Bad .className { color: #fff; } // Good .class-name { color: #fff; } ``` 應該使用類名代替標記名選擇器. 在 CSS 中不建議使用標記名稱選擇器，因為它們會影響層次結構中的意外元素. 另外，由于它們不是有意義的名稱，因此不會在代碼中添加含義. ``` // Bad ul { color: #fff; } // Good .class-name { color: #fff; } ``` ### Formatting[](#formatting "Permalink") 大括號前應始終使用空格，大括號應位于同一行上，每個屬性都應具有自己的行，并且屬性與其值之間應有一個空格. ``` // Bad .container-item { width: 100px; height: 100px; margin-top: 0; } // Bad .container-item { width: 100px; height: 100px; margin-top: 0; } // Bad .container-item{ width:100px; height:100px; margin-top:0; } // Good .container-item { width: 100px; height: 100px; margin-top: 0; } ``` 請注意，單行規則集是一個例外，盡管通常不建議使用這些規則集. ``` p { margin: 0; padding: 0; } ``` ### Colors[](#colors "Permalink") 十六進制（十六進制）顏色應盡可能使用簡寫形式，并應使用小寫字母區分字母和數字，例如`#E3E3E3`與`#e3e3e3` . ``` // Bad p { color: #ffffff; } // Bad p { color: #FFFFFF; } // Good p { color: #fff; } ``` ### Indentation[](#indentation "Permalink") 縮進應始終為每個縮進級別使用兩個空格. ``` // Bad, four spaces p { color: #f00; } // Good p { color: #f00; } ``` ### Semicolons[](#semicolons "Permalink") 在每個屬性后面都應始終包含分號. 縮小樣式表后，分號將自動刪除. ``` // Bad .container-item { width: 100px; height: 100px } // Good .container-item { width: 100px; height: 100px; } ``` ### Shorthand[](#shorthand "Permalink") 簡寫形式應用于支持它的屬性. ``` // Bad margin: 10px 15px 10px 15px; padding: 10px 10px 10px 10px; // Good margin: 10px 15px; padding: 10px; ``` ### Zero Units[](#zero-units "Permalink") 省略長度單位為零的值，這是不必要的，不包括長度單位的性能更高. ``` // Bad .item-with-padding { padding: 0px; } // Good .item-with-padding { padding: 0; } ``` ### Selectors with a `js-` Prefix[](#selectors-with-a-js--prefix "Permalink") 不要將任何以`js-`選擇器用于樣式目的. 這些選擇器僅可與 JavaScript 一起使用，以便在不破壞樣式的情況下進行刪除或重命名. ### IDs[](#ids "Permalink") 不要在 CSS 中使用 ID 選擇器. ``` // Bad #my-element { padding: 0; } // Good .my-element { padding: 0; } ``` ### Variables[](#variables "Permalink") 在為顏色或尺寸添加新變量之前，請確保： * 還沒有一個 * 我們沒有類似的替代方法. ## Linting[](#linting "Permalink") 我們使用[SCSS Lint](https://github.com/sds/scss-lint)檢查樣式指南的一致性. 它使用`.scss-lint.yml`的規則集，該規則集位于項目的主目錄中. 要檢查您的更改是否會產生任何警告，您可以在 GitLab 目錄中運行`rake scss_lint` . SCSS Lint 也將在 GitLab CI / CD 中運行以捕獲任何警告. 如果 Rake 任務發出了您不了解的警告，SCSS Lint 的文檔將包含[其](https://github.com/sds/scss-lint/blob/master/lib/scss_lint/linter/README.md)短毛絨的[完整列表](https://github.com/sds/scss-lint/blob/master/lib/scss_lint/linter/README.md) . ### Fixing issues[](#fixing-issues "Permalink") 如果要自動更改大部分代碼庫以符合 SCSS 樣式指南，則可以使用[CSSComb](https://github.com/csscomb/csscomb.js) . 首先安裝[Node](https://github.com/nodejs/node)和[NPM](https://s0www0npmjs0com.icopy.site/) ，然后運行`npm install csscomb -g`全局（系統范圍）安裝 CSSComb. 使用`csscomb app/assets/stylesheets`在 GitLab 目錄中運行它，以自動修復 CSS / SCSS 問題. 請注意，這并不能解決所有問題，但應該可以解決大多數問題. ### Ignoring issues[](#ignoring-issues "Permalink") 如果您希望`// scss-lint:disable RuleName`忽略一條線或一組線，則可以使用`// scss-lint:disable RuleName` （ [更多信息](https://github.com/sds/scss-lint#disabling-linters-via-source) ）： ``` // This lint rule is disabled because it is supported only in Chrome/Safari // scss-lint:disable PropertySpelling body { text-decoration-skip: ink; } // scss-lint:enable PropertySpelling ``` 確保在`disable`規則上方的行上添加了注釋，否則短絨棉絨將拋出警告. 已啟用`DisableLinterReason`以確保不忽略樣式指南，并與其他人交流為什么在這種情況下忽略樣式指南.