#Google HTML&CSS規範指南

jaycethanks發表於2020-07-01
GoHTMLCSS

翻譯自原文

目錄

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="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

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

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

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

/* 推薦 */
@import 'https://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)，就沒有必要使用實體引用，例如 &mdash;,&rdquo;,&#x263a;。

唯一的例外就是當在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="https://www.google.com/css/maia.css" type="text/css">

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

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

<!-- 推薦 -->
<script src="https://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("https://www.google.com/css/maia.css");

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

/* 推薦 */
@import url(https://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 {}

最後的話

始終保持前後一致

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

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

的註釋周圍也有小方框。

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

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

果您新增到檔案中的程式碼看起來與周圍的現有程式碼完全不同，則當讀者閱讀檔案時，會使

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

翻譯自原文

相關文章