SCSS style guide

原文：https://docs.gitlab.com/ee/development/fe_guide/style/scss.html

SCSS style guide

本样式指南为 SCSS 推荐了最佳做法，以使样式易于阅读，易于维护并为最终用户提供高性能.

Rules

我们的 CSS 是现有方法和旧方法的结合. 这意味着有时可能难以按照本指南进行操作. 这意味着您肯定会遇到例外，在这种情况下，如果不付出巨大的努力，很难甚至不可能遵循该指南. 在这种情况下，您可以与审核者和维护者一起确定不符合这些规则的方法. 请努力限制这些情况.

Utility Classes

为了减少随着站点的增加而产生更多 CSS 的可能性，与添加新 CSS 相比，更喜欢使用实用程序类. 在复杂的情况下，可以通过添加组件类来解决 CSS.

Where are utility classes defined?

优先使用在 GitLab UI 中定义的实用程序类 . 在 Unpkg 上也可以看到一个简单的类列表.

在类utilities.scss和common.scss被弃用. 应该避免使用common.scss中的非设计系统值的类，而采用一致的值.

Avoid Bootstrap’s Utility Classes.

Where should I put new utility classes?

如果尚未将所需的类添加到 GitLab UI，则可以添加它！ 请遵循实用程序文件中记录的命名模式，并参阅GitLab UI 的 CSS 文档以获取更多详细信息，尤其是有关添加响应式和有状态规则的信息.

如果它是不可能等待 GitLab UI 更新（通常一天），将该类添加到utilities.scss按照 GitLab UI 文件相同的命名约定. 应该解决将类反向移植到 GitLab UI 并将其从 GitLab 中删除的后续问题.

When should I create component classes?

我们建议采用”效用至上”的方法.

  1. 从实用程序类开始.
  2. 如果将实用程序类组合到组件类中可以消除代码重复并封装明确的职责，请执行此操作.

这鼓励了组件类的有机增长，并防止创建一次性不可重用的类. 而且，从”效用优先”产生的类的种类倾向于以设计为中心（例如.button ， .alert ， .card ）而不是以领域为中心（例如.security-report-widget ， .commit-header-icon ）.

使用”效用优先”创建的组件类的示例包括：

Inspiration:

Naming

文件名应使用snake_case .

CSS 类应使用lowercase-hyphenated格式，而不是snake_case或camelCase .

  1. // Bad
  2. .class_name {
  3.   color: #fff;
  4. }
  6. // Bad
  7. .className {
  8.   color: #fff;
  9. }
  11. // Good
  12. .class-name {
  13.   color: #fff;
  14. }

应该使用类名代替标记名选择器. 在 CSS 中不建议使用标记名称选择器，因为它们会影响层次结构中的意外元素. 另外，由于它们不是有意义的名称，因此不会在代码中添加含义.

  1. // Bad
  2. ul {
  3.   color: #fff;
  4. }
  6. // Good
  7. .class-name {
  8.   color: #fff;
  9. }

Formatting

大括号前应始终使用空格，大括号应位于同一行上，每个属性都应具有自己的行，并且属性与其值之间应有一个空格.

  1. // Bad
  2. .container-item {
  3.   width: 100px; height: 100px;
  4.   margin-top: 0;
  5. }
  7. // Bad
  8. .container-item
  9. {
  10.   width: 100px;
  11.   height: 100px;
  12.   margin-top: 0;
  13. }
  15. // Bad
  16. .container-item{
  17.   width:100px;
  18.   height:100px;
  19.   margin-top:0;
  20. }
  22. // Good
  23. .container-item {
  24.   width: 100px;
  25.   height: 100px;
  26.   margin-top: 0;
  27. }

请注意，单行规则集是一个例外，尽管通常不建议使用这些规则集.

  1. p { margin: 0; padding: 0; }

Colors

十六进制（十六进制）颜色应尽可能使用简写形式，并应使用小写字母区分字母和数字，例如#E3E3E3与#e3e3e3 .

  1. // Bad
  2. p {
  3.   color: #ffffff;
  4. }
  6. // Bad
  7. p {
  8.   color: #FFFFFF;
  9. }
  11. // Good
  12. p {
  13.   color: #fff;
  14. }

Indentation

缩进应始终为每个缩进级别使用两个空格.

  1. // Bad, four spaces
  2. p {
  3.     color: #f00;
  4. }
  6. // Good
  7. p {
  8.   color: #f00;
  9. }

Semicolons

在每个属性后面都应始终包含分号. 缩小样式表后，分号将自动删除.

  1. // Bad
  2. .container-item {
  3.   width: 100px;
  4.   height: 100px
  5. }
  7. // Good
  8. .container-item {
  9.   width: 100px;
  10.   height: 100px;
  11. }

Shorthand

简写形式应用于支持它的属性.

  1. // Bad
  2. margin: 10px 15px 10px 15px;
  3. padding: 10px 10px 10px 10px;
  5. // Good
  6. margin: 10px 15px;
  7. padding: 10px;

Zero Units

省略长度单位为零的值，这是不必要的，不包括长度单位的性能更高.

  1. // Bad
  2. .item-with-padding {
  3.   padding: 0px;
  4. }
  6. // Good
  7. .item-with-padding {
  8.   padding: 0;
  9. }

Selectors with a js- Prefix

不要将任何以js-选择器用于样式目的. 这些选择器仅可与 JavaScript 一起使用，以便在不破坏样式的情况下进行删除或重命名.

IDs

不要在 CSS 中使用 ID 选择器.

  1. // Bad
  2. #my-element {
  3.   padding: 0;
  4. }
  6. // Good
  7. .my-element {
  8.   padding: 0;
  9. }

Variables

在为颜色或尺寸添加新变量之前，请确保：

  • 还没有一个
  • 我们没有类似的替代方法.

Linting

我们使用SCSS Lint检查样式指南的一致性. 它使用.scss-lint.yml的规则集，该规则集位于项目的主目录中.

要检查您的更改是否会产生任何警告，您可以在 GitLab 目录中运行rake scss_lint . SCSS Lint 也将在 GitLab CI / CD 中运行以捕获任何警告.

如果 Rake 任务发出了您不了解的警告，SCSS Lint 的文档将包含其短毛绒的完整列表 .

Fixing issues

如果要自动更改大部分代码库以符合 SCSS 样式指南，则可以使用CSSComb . 首先安装Node和NPM ，然后运行npm install csscomb -g全局（系统范围）安装 CSSComb. 使用csscomb app/assets/stylesheets在 GitLab 目录中运行它，以自动修复 CSS / SCSS 问题.

请注意，这并不能解决所有问题，但应该可以解决大多数问题.

Ignoring issues

如果您希望// scss-lint:disable RuleName忽略一条线或一组线，则可以使用// scss-lint:disable RuleName （ 更多信息 ）：

  1. // This lint rule is disabled because it is supported only in Chrome/Safari
  2. // scss-lint:disable PropertySpelling
  3. body {
  4.   text-decoration-skip: ink;
  5. }
  6. // scss-lint:enable PropertySpelling

确保在disable规则上方的行上添加了注释，否则短绒棉绒将抛出警告. 已启用DisableLinterReason以确保不忽略样式指南，并与其他人交流为什么在这种情况下忽略样式指南.