#Google HTML&CSS規範指南

2020 年 7 月 1 日
筆記
代碼規範

翻譯自原文

1. 背景
2. 通用
3. HTML
- 3.1 HTML樣式規則
- 3.2 HTML格式規則
4. CSS
最後的話

1. 背景

本文檔定義了HTML和CSS的樣式以及格式規則，旨在提高協同合作，代碼質量，基礎架構支持。本規則應用於基於HTML和CSS為源代碼的項目。只要保持常規代碼的質量，工具就可以自由地進行混淆、壓縮和編譯。

2. 通用

2.1 通用樣式規則

2.1.1 協議

在可能的情況下，儘可能的使用HTTPS來嵌入內容資源

始終使用HTTPS(https:)來引用圖像和其它的媒體文件，css樣式表，以及js腳本。除非沒有對應的通過HTTPS提供的資源。

<!-- 不推薦: 省略協議規則 -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

<!-- 不推薦: 使用 HTTP -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

<!-- 推薦 -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

/* 不推薦: 省略協議 */
@import '//fonts.googleapis.com/css?family=Open+Sans';

/* 不推薦: 使用 HTTP */
@import '//fonts.googleapis.com/css?family=Open+Sans';

/* 推薦 */
@import '//fonts.googleapis.com/css?family=Open+Sans';

2.2 通用格式規則

2.2.1 縮進

一個縮進等同於兩個空格，不要使用多個tabs或者混用tabs和空格來縮進

<ul>
  <li>Fantastic
  <li>Great
</ul>

.example {
  color: blue;
}

2.3 通用元規則

2.3.1 編碼

使用UTF-8

確保你的編輯器使用了UTF-8字符編碼，沒有位元組順序標記。

通過<meta charset="utf-8">來指定HTML模版和文檔編碼。

不要為樣式表指定字符集，因為樣式表默認是UTF-8字符編碼。

（更多編碼以及何如指定他們，參考LINK）

2.3.2 注釋

在可能的時候，為必要的代碼注釋。

2.3.3 操作項

使用TODO來標記代辦事項和操作項

高亮的顯示待辦事項，僅使用TODO，不要使用其它的常見格式，例如@@。

在括號中去綴加用戶名或者郵箱列表之類的聯繫方式，如TODO(聯繫方式)。

在冒號後面綴加操作項，如TODO:操作項。

{# TODO(john.doe): revisit centering #}
<center>Test</center>

<!-- TODO: remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

3. HTML

3.1 HTML樣式規則

3.1.1 文檔類型

使用HTML5

HTML5 標記<!DOCTYPE html>是所有HTML文檔的首選。

（建議使用HTML，即text/html，不要使用XHTML，即application/xhtml+xml，因為缺少瀏覽器和基礎架構支持，並且比HTML提供更少的優化空間。）

不要關閉void元素（非文字內容元素，也叫空元素），例如使用<br>而不是</br>。

3.1.2 HMTL有效性

儘可能使用有效的HTML，除非由於文件大小的其他無法達到的性能目標而無法這樣做。

可以使用像W3C HTML validator這樣的工具去檢測。
使用有效的HTML是一個可測量的基本質量指標，有效的HTML代碼有助於了解技術要求和約束，並且確保正確的使用HTML。

<!-- 不推薦 -->
<title>Test</title>
<article>This is only a test.

<!-- 推薦 -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

3.1.3 語義化

根據不同的目的去使用不同的HTML標籤

根據目的去使用合適的HTML標籤，對於html文檔的可訪問性，復用，以及代碼效率等原因都起着重要的作用。

<!-- 不推薦 -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- 推薦 -->
<a href="recommendations/">All recommendations</a>

3.1.4 為多媒體內容留下挽救方案

為多媒體替代的內容

對於對媒體資源，像圖片，視頻，使用canvas實現的動畫對象，要確保提供可替代的內容，對於圖片而言，應該指定有意義的替代文本（alt屬性），對於音視頻，如果可能的情況下，應當提供對應的文本和字幕。

提供可替代的內容對提高可訪問性而言是很重要的，如果沒有alt屬性，盲人用戶幾乎無法知道圖片是關於什麼，而其它用戶也有可能沒辦法理解音視頻是什麼內容。

<!-- 不推薦 -->
<img src="spreadsheet.png">

<!-- 推薦 -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

（對於圖像而言，alt屬性有時候也會造成冗餘，例如，對於用於裝飾用的圖片，不具備實際含義，就不應當指定alt屬性，即alt=""。）

3.1.5 業務分離

應當把文檔結構、表現樣式、和行為分開。

嚴格的保持文檔結構（markup），表現樣式（styling）和行為（scripting）分離，並且應該盡量的讓這三部分相互影響達到最小。

為了實現這一目的，要確保文檔和模版只含有HTML代碼，且HTML代碼僅用於提供布局結構的作用，把所有的樣式都放在樣式表中，把所有的行為全都放在腳本中。

另外，通過從文檔和模板中鏈接儘可能少的樣式表和腳本，使聯繫區域儘可能小。

項目的可維護性，分離結構和樣式以及行為是十分必要的。從樣式表和腳本文件中去修改相應邏輯遠比直接在html中去修改代價小。

<!-- 不推薦 -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I』ve read about this on a few sites but now I』m sure:
  <u>HTML is stupid!!1</u>
<center>I can』t believe there』s no way to control the styling of
  my website without doing everything all over again!</center>

<!-- 推薦 -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I』ve read about this on a few sites but today I』m actually
  doing it: separating concerns and avoiding anything in the HTML of
  my website that is presentational.
<p>It』s awesome!

3.1.6 實體引用

不要使用實體引用

假設文件和編輯器以及團隊之間使用相同的編碼(UTF-8)，就沒有必要使用實體引用，例如 —,”,☺。

唯一的例外就是當在HTML中表示特殊含義字符的時候，起到類似轉義的作用，（例如<和&）,以及一些不可見的字符（例如不間斷空格）。

<!-- 不推薦 -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- 推薦 -->
The currency symbol for the Euro is 「€」.

3.1.7 可選的標籤

省略可選的標籤

為了優化文件大小和便於掃面，請考慮省略可選的標記，HTML5規範（HTML5 specification ）定義了那些標記可以被省略。

(這種方法可能需要一段寬限期來作為更廣泛的指導原則，因為它與web開發人員通常被教導的內容有很大的不同。出於一致性和簡單性的原因，最好忽略所有可選標記，而不僅僅是一個選項。)

<!-- 不推薦 -->
<!DOCTYPE html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>

<!-- 推薦 -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.

3.1.8 `type`屬性

為樣式表和腳本省略type屬性

不要使用type屬性為樣式表和腳本指明文件類型，除非用的不是css和javascript。

因為HTML5默認指定了type為text/css以及text/javascript,所以在文檔中再去使用type屬性明確文件類型是不必要的。

<!-- 不推薦 -->
<link rel="stylesheet" href="//www.google.com/css/maia.css" type="text/css">

<!-- 推薦 -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">

<!-- 不推薦 0-->
<script src="//www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>

<!-- 推薦 -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

3.2 HTML格式規則

3.2.1 通用格式

每一個塊區、列表或者表格都應該在新的一行中開始，並且，縮進每個子元素。

(如果您遇到列表項之間存在空格的問題，可以將所有li元素放在一行中。鼓勵linter拋出警告而不是錯誤。)

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe
  <li>Larry
  <li>Curly
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income
      <th scope="col">Taxes
  <tbody>
    <tr>
      <td>$ 5.00
      <td>$ 4.50
</table>

3.2.2 HTML 換行

斷開長行（可選的）

雖然對於HTML沒有限制列的建議，但是如果可以顯著提高可讀性，可以考慮換行。

當換行之後，每一個銜接行都應該至少額外多縮緊4個空格。

<md-progress-circular md-mode="indeterminate" class="md-accent"
    ng-show="ctrl.loading" md-diameter="35">
</md-progress-circular>

<md-progress-circular
    md-mode="indeterminate"
    class="md-accent"
    ng-show="ctrl.loading"
    md-diameter="35">
</md-progress-circular>

<md-progress-circular md-mode="indeterminate"
                      class="md-accent"
                      ng-show="ctrl.loading"
                      md-diameter="35">
</md-progress-circular>

3.2.3 HTML 引號

當引用屬性值的時候，使用雙引號

使用雙引號（""）和不是單引號去包裹屬性值。.

<!-- 不推薦 -->
<a class='maia-button maia-button-secondary'>Sign in</a>

<!-- 推薦 -->
<a class="maia-button maia-button-secondary">Sign in</a>

4. CSS

4.1 CSS樣式規則

4.1.1 CSS 有效性

使用有效的CSS

4.1.2 ID和Class命名

使用有含義的或者通用的ID和Class名。

避免使用描述性的或者晦澀難懂的命名，始終使用反映了元素目的或功能的ID和類名，或者通用的名稱。

特定的且反映目的功能的命名應該儘可能的易於理解且最小的被再次修改的可能性。

通用名稱只是與它們的兄弟姐妹沒有特殊或沒有意義的元素的後備。通常需要它們作為「幫助者」。

使用功能名稱或通用名稱可以減少不必要的文檔或模板更改的可能性

/* 不推薦: meaningless */
#yee-1901 {}

/* 不推薦: presentational */
.button-green {}
.clear {}

/* 推薦: specific */
#gallery {}
#login {}
.video {}

/* 推薦: generic */
.aux {}
.alt {}

4.1.3 ID 和 Class 命名樣式

使用儘可能短但必要的ID和類名。

盡量簡短地傳達ID或類的含義。

以這種方式使用ID和類名有助於提高可接受的可理解性和代碼效率。

/* 不推薦 */
#navigation {}
.atr {}

/* 推薦 */
#nav {}
.author {}

4.1.4 類型選擇器（Type Selectors）

避免使用類型選擇器來限定ID和類名。

除非必要(例如使用helper類)，否則不要將元素名與id或類結合使用。

避免不必要的祖先選擇器有助於提高性能(performance reasons)。

/* 不推薦 */
ul#example {}
div.error {}

/* 推薦 */
#example {}
.error {}

4.1.5 簡寫屬性

儘可能的使用簡寫屬性

CSS提供了很多的簡寫屬性，例如font，我們應當儘可能的使用簡寫屬性，即便只有一個需要被顯示設定的屬性值。

使用簡寫屬性有助於我們理解代碼，且有助於代碼效率。

/* 不推薦 */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;

/* 推薦 */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;

4.1.6 0 和單位

如非必要，我們應該總是省略屬性值為0時的單位，例如0px。

flex: 0px; /* This flex-basis component requires a unit. */
flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */
margin: 0;
padding: 0;

4.1.7 前置 0

省略屬性值中的前置0

不要在值或者長度介於-1到1之間的值中使用0.

font-size: .8em;

4.1.8 十六進制表示法

如非必要，儘可能的使用三位十六進制表示法

對於允許的顏色值，三個字符的十六進制表示法更短，更簡潔。

/* 不推薦 */
color: #eebbcc;

/* 推薦 */
color: #ebc;

4.1.9 前綴

在大型項目以及嵌入到其他項目或外部站點中的代碼中，請使用前綴（作為名稱空間）作為ID和類名。使用簡短的唯一標識符，後接破折號。、

使用名稱空間有助於防止命名衝突，並可以簡化維護，例如在搜索和替換操作中。

.adw-help {} /* AdWords */
#maia-note {} /* Maia */

4.1.10 ID 和 Class 名稱分隔符

在ID或者Class名稱中，使用連接符分開多個單詞

為了提高理解和可掃描性，在選擇器中，除了連字符以外，不要用任何字符連接單詞和縮寫(不包括任何字符)。

/* 不推薦: 不分開單詞 「demo」和 「image」 */
.demoimage {}

/*  不推薦: 使用下劃線而不是連接符 */
.error_status {}

/* 推薦 */
#video-id {}
.ads-sample {}

4.1.11 黑客

避免用戶代理檢測和CSS”黑客攻擊”，首先嘗試其他方法。

通過用戶代理檢測或特殊的CSS過濾器、變通方法和hack來解決樣式差異是很誘人的。這兩種方法都應該作為最後的手段，以實現和維護一個有效的、可管理的代碼庫。換句話說，從長遠來看，給檢測和黑客提供免費通行證將損害項目，因為項目往往會採取阻力最小的方式。也就是說，允許並簡化檢測和破解意味着更頻繁地使用檢測和破解太頻繁了。

4.2 CSS格式規則

4.2.1 聲明順序

按照字母順序進行聲明

將聲明按照字母順序進行排列，以便以一種易於記憶和維護的方式實現一致性的代碼。

忽略供應商特定的前綴以進行排序。然而，針對某個CSS屬性的多個供應商特定的前綴

應該保持排序。

background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;

4.2.2 塊中內容縮進

縮進所有的塊級內容

這是規則以及聲明中的規則，以便反映層次結構並增進理解。

@media screen, projection {

  html {
    background: #fff;
    color: #444;
  }

}

4.2.3 聲明終止

使用分號以結束每行聲明

出於一致性和可擴展性的原因，每個聲明都以分號結尾。

/* 不推薦 */
.test {
  display: block;
  height: 100px
}

/* 推薦 */
.test {
  display: block;
  height: 100px;
}

4.2.4 屬性名終止

在每個屬性名的冒號後，屬性值之前，用一個空格隔開

始終在最後一個選擇器之後，和開括號之前用一個空格隔開

開括號應該和最後一個選擇器始終在同一行

/* 不推薦: 缺失空格 */
#video{
  margin-top: 1em;
}

/* 不推薦: 不必要的折行 */
#video
{
  margin-top: 1em;
}

/* 推薦 */
#video {
  margin-top: 1em;
}

4.2.6 選擇器和聲明分離

通過折行來分割不同的選擇器和聲明

每一個選擇器始終從新的一行開始

/* 不推薦 */
a:focus, a:active {
  position: relative; top: 1px;
}

/* 推薦 */
h1,
h2,
h3 {
  font-weight: normal;
  line-height: 1.2;
}

4.2.7 分割樣式規則

始終通過新的空行來分離不同的樣式規則

html {
  background: #fff;
}

body {
  margin: auto;
  width: 50%;
}

4.2.8 CSS 引號使用規則

為屬性選擇器和屬性值應用單引號（''），而不是雙引號（””）

URL 值不要使用引號

例外：除非你使用 @charset 規則, 才會用到雙引號—single quotation marks are not permitted.

/* 不推薦 */
@import url("//www.google.com/css/maia.css");

html {
  font-family: "open sans", arial, sans-serif;
}

/* 推薦 */
@import url(//www.google.com/css/maia.css);

html {
  font-family: 'open sans', arial, sans-serif;
}

4.3 CSS元規則

4.3.1 節注釋

通過注釋對節進行分組（可選的）

儘可能的使用注釋對不同的節進行分組，不同的分組間用紅白行來分隔。

/* Header */

#adw-header {}

/* Footer */

#adw-footer {}

/* Gallery */

.adw-gallery {}

最後的話

始終保持前後一致

如果您正在編輯代碼，請花幾分鐘時間查看您周圍的代碼並確定其樣式。如果他們在所

有算術運算符周圍使用空格，您也應該這樣做。如果他們的注釋周圍有小方框，則使您

的注釋周圍也有小方框。

制定樣式指南的目的是擁有通用的編碼詞彙，以便人們可以專註於您在說的而不是在怎麼

說。我們在這裡介紹全局樣式規則，以便人們了解詞彙表，但是局部樣式也很重要。如

果您添加到文件中的代碼看起來與周圍的現有代碼完全不同，則當讀者閱讀文件時，會使

他們的節奏變慢。避免這種情況。

翻譯自原文

Tags: 代碼規範