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 程式碼段。我們“試一試”部分中的互動式示例通常都按照此頁面上描述的指南編寫。