CSS 程式碼示例編寫指南 - MDN Web Docs

CSS 程式碼示例通用指南

選擇格式

關於正確縮排、空格和行長度的看法一直備受爭議。關於這些話題的討論會分散建立和維護內容的注意力。

在 MDN Web 文件中，我們使用 Prettier 作為程式碼格式化程式，以保持程式碼風格一致（並避免離題討論）。您可以查閱我們的配置檔案以瞭解當前規則，並閱讀 Prettier 文件。

Prettier 格式化所有程式碼並保持風格一致。然而，還有一些額外的規則需要您遵循。

規劃你的 CSS

在深入編寫大量 CSS 程式碼之前，請仔細規劃你的樣式。需要哪些通用樣式，你需要建立哪些不同的佈局，需要建立哪些特定的覆蓋，以及它們是否可重用？最重要的是，你需要儘量避免過多的覆蓋。如果你發現自己一直在編寫樣式，然後又在幾條規則之後取消它們，你可能需要重新考慮你的策略。

在支援時使用現代 CSS 特性

一旦所有主流瀏覽器——Chrome、Edge、Firefox 和 Safari——都支援新特性（即基線），你就可以使用它們。

此規則不適用於頁面上正在文件化的 CSS 特性（這由包含標準決定）。例如，你可以文件化非標準或實驗性特性，並編寫完整的示例來演示它們的行為，但你應該避免在其他不相關特性的演示中使用這些特性，例如 Web API。

遵循常見的最佳實踐

有一些普遍公認的原則，我們不需要在這裡詳盡地說明

確保你的程式碼沒有語法錯誤，這可能導致屬性或宣告被忽略。如果符合我們關於現代 CSS 特性的通用規則，未實現的標準語法是可以接受的。
不要使用非標準、已棄用或已過時的特性。此指南也適用於帶字首的特性：僅當標準特性不可用時才使用帶字首的替代方案（參見我們關於現代 CSS 特性的通用規則）。如果讀者需要更廣泛的相容性，他們可以自己新增帶字首的備用方案或使用 CSS 後處理器。
不要編寫冗餘或無功能程式碼，這通常是 Bug 或重構遺留程式碼的常見指示。這包括宣告中重複的屬性、空宣告、空註釋或不匹配任何元素的選擇器。

不要使用預處理器

不要在示例程式碼中使用預處理器語法，例如 Sass、Less 或 Stylus。在 MDN Web Docs 上，我們記錄了純 CSS 語言。使用預處理器只會提高理解示例的門檻，可能會讓讀者感到困惑。

不要使用特定的 CSS 方法論

與上一條指南的精神相同，不要在 MDN Web Docs 上使用特定的 CSS 方法論（例如 BEM 或 SMACSS）編寫示例程式碼。即使它們是有效的 CSS 語法，命名約定也可能讓不熟悉這些方法論的人感到困惑。

不要使用重置

為了最大程度地控制跨平臺的 CSS，許多人過去常常使用 CSS 重置來刪除所有樣式，然後再自己構建。這當然有其優點，但特別是在現代世界中，CSS 重置可能矯枉過正，導致花費大量額外時間重新實現原本並非完全損壞的東西，例如預設邊距和列表樣式。

正式語法是 MDN CSS 文件不可或缺的一部分（例如，請參閱 background-image 屬性頁面上的正式語法部分）。由於許多開發人員熟悉這種格式的語法，因此在描述和示例中以類似正式語法的方式編寫虛擬碼是可以接受的。但是，任何不符合語法規範的 CSS 程式碼都不應標記為 CSS。css 程式碼塊中的語法錯誤會導致靜態檢查器無法解析程式碼，使期望看到有效 CSS 程式碼的讀者感到困惑，甚至可能導致毫無意義的語法高亮。要麼將你的程式碼塊標記為 plain，要麼使用 CSSSyntaxRaw 宏來渲染完整的正式語法。

不要像這樣寫描述（無論如何這都不是真正的正式語法；它只是帶有佔位符的偽 CSS）

The `border` property has the following general form:

```css
border: <border-width> <border-style> <border-color>;
```

相反，使用 plain

The `border` property has the following general form:

```plain
border: <border-width> <border-style> <border-color>;
```

或者，當你覺得合適時，使用 CSSSyntaxRaw 宏編寫實際的正式語法

The `border` property is specified as a line width, a line style, and a color, in any order:

{{CSSSyntaxRaw(`border = <line-width> || <line-style> || <color>`)}}

此外，單個值在語法上並非格式良好的 CSS。CSS 程式碼至少需要一個屬性及其值。如果你要文件化 rgb() 函式，請這樣寫

css

color: rgb(31 41 59);
color: rgb(31 41 59 / 26%);

不要使用這種風格

css

rgb(31 41 59);
rgb(31 41 59 / 26%);

請注意，此規則不適用於“語法”部分中的第一個程式碼塊，該程式碼塊由語法部分指定，並且要求函式在沒有屬性名稱的情況下編寫。

動畫

關鍵幀選擇器

指定關鍵幀時，0% 和 100% 選擇器也可以寫成 from 和 to。如果 @keyframes 規則只包含這兩個選擇器，請使用 from 和 to 而不是 0% 和 100%。這使你的程式碼更具語義性。

所以避免這樣

css

@keyframes example {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

改為使用 from 和 to

css

@keyframes example {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

另一方面，如果你的 @keyframes 規則包含的不僅僅是開始和結束幀，請使用 0% 和 100% 選擇器以保持一致性。

css

@keyframes example {
  0% {
    opacity: 0;
  }
  50% {
    opacity: 0.8;
  }
  100% {
    opacity: 1;
  }
}

層疊、屬性和選擇器

控制特異性

如果可能，請避免因增加或減少特異性而產生的意外，例如過度使用:where() 偽類或重複選擇器。相反，請考慮以下技術來管理特異性

更改宣告的順序以利用層疊
重新排列每個宣告中的屬性，使它們不會相互覆蓋
在 HTML id 本身合理的情況下使用 ID 選擇器

!important

!important 是最後的手段，通常只在你需要覆蓋某些內容且沒有其他方法時使用。使用 !important 是一種不良做法，應儘可能避免。

css

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

排序

通常，當兩個宣告針對相同元素時，特異性較高的宣告應在樣式表中靠後。

css

button {
  color: blue;
}

.my-form button {
  color: red;
}

在宣告中，最好將相關屬性（例如尺寸、定位和顏色）放在一起。自定義屬性應在宣告塊的頂部宣告，這允許快速識別所有可用的自定義屬性。

空行

建議在宣告塊之間使用空行。如果連續的宣告高度相關，例如同一實用程式的變體，則可以刪除它們。

屬性之間的空行應謹慎使用。僅當每組屬性形成清晰的語義塊時才新增它們。

簡寫屬性

如果簡寫屬性的每個組成屬性都分配了一個非預設值，請使用簡寫屬性而不是組成的長手屬性。這使你的程式碼更短，更容易閱讀。

替換這些長手屬性
css
```
margin-top: 1em;
margin-right: 2em;
margin-bottom: 1em;
margin-left: 2em;
```
使用它們對應的簡寫
css
```
margin: 1em 2em;
```
如果簡寫屬性的部分組成屬性分配了非預設值，則簡寫屬性的使用是可選的。以下兩種情況都是可以接受的
css
```
margin-top: 1em;
margin-bottom: 1em;
```
css
```
margin: 1em 0;
```

使用最短的簡寫語法。這樣寫

css

margin: 1em;

避免這些

css

margin: 1em 1em;
margin: 1em 1em 1em 1em;

以規範順序編寫簡寫屬性。這樣寫

css

/* width style color */
border: 1px solid red;

不要這樣寫

css

border: solid red 1px;

對於每個簡寫，要麼使用它，要麼使用它的長手組成部分，絕不能混用，因為覆蓋關係複雜且容易出錯。避免這些

css

margin-top: 1em;
margin: 2em; /* Oops, margin-top is ignored */

border-width: 1px;
border-bottom-width: 5px; /* Overrides one border's width *only* */

使用類選擇器

通常，首選類選擇器（並在 HTML 中使用 class 而不是 id）。它們可以組合：多個元素可以使用相同的類，同一個類也可以用於多個元素。

css

.footnote {
  /* ... */
}

css

#footnote {
  /* ... */
}

使用類進行樣式設定，並將 ID 保留用於非 CSS 用途，例如在 JavaScript 中使用或連結到唯一的頁面錨點（<a href="#section1">）。在 ID 的使用合理的情況下，你可以將其用作選擇器，可能用於控制特異性。

舊的偽元素選擇器

::before、::after、::first-letter 和 ::first-line 偽元素也可以用單個冒號編寫（如 :before）。避免使用單冒號語法，因為它不被推薦，並且可能被讀者誤認為是偽類（:hover）。

複雜選擇器列表

:is()、:where() 和 :not() 偽類接受複雜選擇器列表。使用它們來縮短你的選擇器。

這樣寫

css

input:not(:checked, :disabled) {
  /* ... */
}

不要這樣寫

css

input:not(:checked):not(:disabled) {
  /* ... */
}

大小寫

預設情況下，所有識別符號都應為小寫。這適用於選擇器、函式和關鍵字。自定義識別符號應使用kebab-case，例如 --custom-property 或 my-animation。有關作為 CSS 選擇器引用的 HTML ID 和類的命名約定，請參閱 HTML 樣式指南。

例外情況包括 SVG 中定義的關鍵字值，由於歷史原因它們是camelCase，並且應該這樣編寫以增強可讀性。這些關鍵字包括：currentColor、text-rendering 值、shape-rendering 值、pointer-events 值和 color-interpolation-filters 值。

顏色

選擇表示法

通常，如果特定的調色盤不是問題，預設使用常見的命名顏色。例如，使用 black 而不是 rgb(0 0 0) 或 #000000，以及 green 而不是 chartreuse。

如果需要特定顏色，預設使用 rgb() 表示法。hsl() 和其他函式應僅在特定表示法有意義（例如，色輪或漸變）時使用。十六進位制表示法更簡潔，但可讀性可能較差；它可以與 rgb() 互換，具體取決於你覺得哪個更方便。

無論你使用哪種顏色函式，始終使用現代語法（rgb(31 41 59 / 0.26)），而不是舊的逗號分隔語法。始終使用不帶 a 字尾的函式（rgb 而不是 rgba），因為它更短，並且如果你以後決定新增或刪除 alpha 通道，則無需更改名稱。

使用十六進位制表示法時，始終使用六（或八）位版本，以避免認知負擔：#aabbcc 而不是 #abc。

顏色引數

為了保持一致性，所有引數預設應使用數字而不是百分比或度數。這也適用於 alpha 通道。但是，如果特定表示法有意義（例如，在動畫、漸變或計算中），請在上下文中使用合適的型別。

如果 alpha 通道為 1，則省略它。寫 rgb(31 41 59) 而不是 rgb(31 41 59 / 1)。

選擇顏色

除了推薦使用常見命名顏色外，你的調色盤還應符合我們的可訪問性指南。特別是，如果顏色區分元素（例如“紅色框”和“藍色框”），請確保顏色對色覺缺陷的人是可區分的。文字和背景之間的對比度（WCAG AA）目標至少為 4.5:1。

註釋

使用 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

body {
  font-family: "Helvetica";
}

css

body {
  /* The "sans-serif" family is not needed because Arial is a web-safe font */
  font-family: "Helvetica", "Arial";
}

math {
  font-family: "Latin Modern Math", "STIX Two Math", math;
}

指定字型粗細

首選關鍵字值，例如 normal 和 bold，以及相對粗細，例如 bolder 和 lighter。僅在需要特定粗細時使用數字值。你應該始終用 normal 替換 400，用 bold 替換 700，除非在使用可變字型聲明範圍，或為了與其他類似宣告保持一致。

長度

使用彈性/相對單位

為了在最廣泛的裝置範圍內實現最大靈活性，所有長度都預設使用相對單位，例如 em、rem、百分比和視口單位（如果你希望它們根據視口寬度而變化）。你可以在我們的CSS 值和單位指南中閱讀更多相關內容。

這樣寫

css

margin: 0.5em;
max-width: 50%;

避免這樣

css

margin: 20px;
max-width: 500px;

媒體查詢

範圍語法

使用現代範圍語法而不是 min- 和 max-。前者允許指定排他範圍，允許同時指定上限和下限，並且總體上更簡潔易讀。

css

@media (width >= 480px) {
  /* ... */
}
@media (600px < height < 900px) {
  /* ... */
}

css

@media (min-width: 480px) {
  /* ... */
}
@media (min-height: 600px) and (max-height: 900px) {
  /* ... */
}

此原則延伸到媒體查詢的非 CSS 用法，例如 <link> 元素的 media 屬性或 window.matchMedia()。

如果你有透過媒體閾值選擇的不同替代樣式，請特別注意你的媒體查詢。請記住，width 和 height 可以是分數，確保在每個值下，只有一個替代樣式生效。

移動優先媒體查詢

在包含針對不同目標視口大小的媒體查詢樣式的樣式表中，首先包含窄螢幕/移動樣式，然後再遇到任何其他媒體查詢。透過連續的媒體查詢新增更寬視口大小的樣式。遵循此規則有許多優點，這些優點在響應式設計中進行了解釋。

css

/* Default CSS layout for narrow screens */

@media (width >= 480px) {
  /* CSS for medium width screens */
}

@media (width >= 800px) {
  /* CSS for wide screens */
}

@media (width >= 1100px) {
  /* CSS for really wide screens */
}

字串

在 CSS 語法中引號可選的地方，請使用它們，並使用雙引號。這樣做

css

[data-vegetable="liquid"] {
  background-image: url("../../media/examples/lizard.png");
  font-family: "Helvetica", "Arial";
}

不要這樣做，因為允許的字元型別更受限制，有時會導致細微的語法錯誤

css

[data-vegetable=liquid] {
  background-image: url(../../media/examples/lizard.png);
  font-family: Helvetica, Arial;
}

使用 @import at-rule 時，將模組路徑指定為字串，而不是 url()。

css

@import "style.css";

css

@import url("style.css");

另見

CSS 參考索引 - 瀏覽我們的 CSS 屬性參考頁面，檢視一些優秀、簡潔、有意義的 CSS 片段。“試一試”部分中的互動式示例通常遵循此頁面中描述的指南。

幫助改進 MDN

瞭解如何貢獻

此頁面由 MDN 貢獻者最後修改於 ⁨2025 年 8 月 3 日⁩。

在 GitHub 上檢視此頁面 • 報告此內容問題