# 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`以确保不忽略样式指南，并与其他人交流为什么在这种情况下忽略样式指南.