CSS 代码示例编写指南

以下指南涵盖了如何为 MDN Web Docs 编写 CSS 示例代码。

CSS 代码示例的一般指南

选择格式

关于正确缩进、空格和行长的观点一直存在争议。关于这些主题的讨论会分散创建和维护内容的注意力。

在 MDN Web Docs 上，我们使用 Prettier 作为代码格式化程序，以保持代码风格的一致性（并避免无关的讨论）。您可以查阅我们的配置文件以了解当前规则，并阅读 Prettier 文档。

Prettier 格式化所有代码并保持样式一致。但是，您还需要遵循一些其他规则。

计划您的 CSS

在深入编写大量 CSS 代码之前，请仔细规划您的样式。需要哪些通用样式，需要创建哪些不同的布局，需要创建哪些特定的覆盖，它们是否可重用？最重要的是，您需要尝试**避免过度覆盖**。如果您发现自己不断编写样式，然后在接下来的几条规则中再次取消它们，那么您可能需要重新考虑您的策略。

使用灵活/相对单位

为了在尽可能广泛的设备上实现最大的灵活性，最好使用相对单位（如 em 和 rem 或百分比和视口单位）来调整容器、填充等的大小，如果您希望它们根据视口宽度而变化。您可以在我们的 CSS 值和单位指南中了解更多相关信息。

不要使用预处理器

在示例代码中不要使用预处理器语法，例如 Sass、Less 或 Stylus。在 MDN Web Docs 上，我们记录的是原生 CSS 语言。使用预处理器只会增加理解示例的难度，可能会让读者感到困惑。

不要使用特定的 CSS 方法

本着与上一条指南相同的精神，不要在 MDN Web Docs 上使用特定的 CSS 方法（如 BEM 或 SMACSS）来编写示例代码。即使它们是有效的 CSS 语法，但命名约定对于不熟悉这些方法的人来说也可能令人困惑。

不要使用重置

为了最大程度地控制跨平台的 CSS，许多人过去使用 CSS 重置来删除所有样式，然后自己重新构建。这当然有其优点，但尤其是在现代世界中，CSS 重置可能有点过分，导致花费大量额外的时间重新实现原本没有完全损坏的东西，例如默认边距、列表样式等。

如果您确实觉得需要使用重置，请考虑使用 Nicolas Gallagher 的 normalize.css，它旨在使跨浏览器的样式更加一致，消除一些我们总是删除的默认烦恼（例如 <body> 上的边距）并修复一些错误。

!important

!important 是最后的手段，通常仅在您需要覆盖某些内容且没有其他方法可以做到时才会使用。使用 !important 是一种不好的做法，您应该尽可能避免使用它。

css

.bad-code {
  font-size: 4rem !important;
}

CSS 注释

使用 CSS 样式注释来注释非自文档的代码。另请注意，您应该在星号和注释之间留一个空格。

css

/* This is a CSS-style comment */

将注释放在它们引用的代码之前的单独行上，如下所示

css

h3 {
  /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */
  text-shadow: 1px 1px 2px red;
  /* Sets the font-size to double the default document font size */
  font-size: 2rem;
}

值周围使用双引号

在可以或应该包含引号的地方，请使用引号，并使用双引号。例如

css

[data-vegetable="liquid"] {
  background-color: goldenrod;
  background-image: url("../../media/examples/lizard.png");
}

长格式规则与简写规则

通常，在教授 CSS 语法的细节时，使用长格式属性比使用简写格式更清晰、更直观（除非您当然是在通过示例解释简写格式）。请记住，MDN Web Docs 上示例的目的是教人们，而不是耍聪明或追求效率。我们在此解释了为什么建议使用长格式规则编写代码。

简写格式通常更难以理解其作用。在下面的示例中，需要一段时间才能完全理解 font 语法的作用。

css

font: small-caps bold 2rem/1.5 sans-serif;

而以下样式则更清晰

css

font-variant: small-caps;
font-weight: bold;
font-size: 2rem;
line-height: 1.5;
font-family: sans-serif;

CSS 简写格式存在潜在的额外陷阱——对于您未明确设置的语法部分，会设置默认值，这可能会导致意外重置您在级联中或其他预期效果中早先设置的值。grid 属性例如，为未指定的项目设置以下所有默认值
- grid-template-rows: none
- grid-template-columns: none
- grid-template-areas: none
- grid-auto-rows: auto
- grid-auto-columns: auto
- grid-auto-flow: row
- column-gap: 0
- row-gap: 0
- column-gap: normal
- row-gap: normal
某些简写格式只有在您以特定顺序包含不同的值组件时才能按预期工作。CSS 动画就是这种情况。在下面的示例中，预期顺序以注释的形式编写
css
```
/* duration | timing-function | delay | iteration-count
  direction | fill-mode | play-state | name */
animation: 3s ease-in 1s 2 reverse both paused slidein;
```
在此示例中，第一个可以解析为 <time> 的值将分配给 animation-duration 属性，第二个可以解析为时间的将分配给 animation-delay。（有关更多信息，请参阅动画语法详细信息。）

移动优先媒体查询

在包含针对不同目标视口大小的媒体查询样式的样式表中，首先在遇到任何其他媒体查询之前包含窄屏幕/移动样式。通过后续的媒体查询添加更宽视口大小的样式。遵循此规则具有许多在移动优先文章中解释的优点。

css

/* Default CSS layout for narrow screens */

@media (min-width: 480px) {
  /* CSS for medium width screens */
}

@media (min-width: 800px) {
  /* CSS for wide screens */
}

@media (min-width: 1100px) {
  /* CSS for really wide screens */
}

选择器

不要使用 ID 选择器，因为它们
- 灵活性较差；如果您发现需要多个，则无法添加更多。
- 更难覆盖，因为它们比类具有更高的特异性。
css
```
.editorial-summary {
  /* ... */
}
```
css
```
#editorial-summary {
  /* ... */
}
```

关闭属性的值

在关闭边框（以及任何其他可以取 0 或 none 作为值的属性）时，请使用 0 而不是 none

css

border: 0;

另请参阅

CSS 参考索引 - 浏览我们的 CSS 属性参考页面以查看一些良好、简洁、有意义的 CSS 代码段。我们“试一试”部分中的交互式示例通常都按照此页面上描述的指南编写。