Google HTML/CSS 风格指南

1、Background 背景

本文档定义了 HTML 和 CSS 的格式和样式规则。它旨在改善协作、代码质量并启用支持基础设施。它适用于使用 HTML 和 CSS 的原始工作文件，包括 GSS 文件。工具可以自由地混淆、缩小和编译，只要通用代码保持质量。

2、常规

2.1、一般样式规则

2.1.1、Protocol 协议

尽可能对嵌入式资源使用 HTTPS。除非相应的文件无法通过HTTPS获取，否则始终使用HTTPS（https:）来加载图像和其他媒体文件、样式表和脚本。

<!-- Not recommended: omits the protocol -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

<!-- Not recommended: uses HTTP -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<!-- Recommended -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

/* Not recommended: omits the protocol */
@import '//fonts.googleapis.com/css?family=Open+Sans';

/* Not recommended: uses HTTP */
@import 'http://fonts.googleapis.com/css?family=Open+Sans';
/* Recommended */
@import 'https://fonts.googleapis.com/css?family=Open+Sans';

2.2、常规格式规则

2.2.1、缩进

一次缩进 2 个空格。不要使用制表符或混合使用制表符和空格进行缩进。

<style>
 .example {
    color: blue;
 }
</style>
<ul>
  <li>Fantastic</li>
  <li>Great</li>
</ul>

2.2.2、Capitalization

仅使用小写字母。属性值（除非 text/CDATA所有代码都必须是小写的：这适用于 HTML 元素名称、属性、 CSS 选择器、属性和属性值（字符串除外）。

<!-- Not recommended -->
<A HREF="/">Home</A>
<!-- Recommended -->
<img src="google.png" alt="Google">

/* Not recommended */
color: #E5E5E5;
/* Recommended */
color: #e5e5e5;

2.2.3、尾随空格

删除尾随的空格。尾随空格是不必要的，并且会使差异复杂化。

<!-- Not recommended -->
<p>What?_
<!-- Recommended -->
<p>Yes please.

2.3、通用 Meta 规则

2.3.1、Encoding 编码

使用 UTF-8（无 BOM）。请确保您的编辑器使用 UTF-8 作为字符编码，并且不使用字节顺序标记。

通过 <meta 在 HTML 模板和文档中指定编码<meta charset="utf-8">。不要指定样式表的编码，因为这些代码假定 UTF-8 格式。

2.3.2、Comments

尽可能根据需要解释代码。使用注释来解释代码：它涵盖了什么，它有什么目的，为什么使用或首选相应的解决方案？（此项目是可选的，因为它不被视为始终的现实期望需要完整记录的代码。对于 HTML 和 CSS 代码，里程可能会有很大差异，并且取决于项目的复杂程度。

2.3.3、Action Items

使用 TODO 标记待办事项和操作项。仅使用关键字 TODO@@ 突出显示待办事项，而不是使用其他常见格式，例如：TODO(contact)在括号中附加联系人（用户名或邮件列表），格式如下在冒号后附加操作项TODO: action item。

{# 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、Document Type 文档类型

使用 HTML5。HTML5（HTML 语法）是所有 HTML 文档的首选：<!DOCTYPE html>。

建议使用HTML（作为text/html）。不要使用XHTML。XHTML（作为application/xhtml+xml）缺乏浏览器和基础设施支持，并且其优化空间比HTML更小。

3.1.2、HTML 有效性

尽可能使用有效的 HTML。使用有效的 HTML 代码，除非由于其他方式无法实现而无法实现有关文件大小的性能目标。使用 W3C HTML 验证程序进行测试。

使用有效的 HTML 是一个可衡量的基准质量属性，有助于了解技术要求和约束，并确保适当的 HTML 用法。

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

3.1.3、语义

根据其目的使用 HTML。使用元素（有时错误地称为“标签”）的本来用途。例如，使用标题元素来创建标题，使用 p 元素来创建段落，使用 a 元素来创建锚点等。

出于可访问性、重用性和代码效率方面的考虑，根据 HTML 的目的来使用 HTML 很重要。

<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- Recommended -->
<a href="recommendations/">All recommendations</a>

3.1.4、多媒体回退

为多媒体提供替代内容。对于多媒体，例如图像、视频、通过canvas文本（alt的动画对象，请确保以提供替代访问。对于图像，这意味着使用有意义的替代方案）以及视频和音频脚本和字幕（如果可用）。

提供替代内容对于无障碍性至关重要：盲用户在没有 @alt 的情况下几乎无法判断图像的内容，而其他用户也可能无法理解视频或音频的内容。

对于其 alt 属性将引入冗余信息的图像，以及您无法立即使用CSS的仅具有装饰性目的的图像，请不使用替代文本，如 alt=""。

<!-- Not recommended -->
<img src="spreadsheet.png">

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

3.1.5、关注点分离

将结构与呈现与行为分开。严格保持结构（标记）、表示（样式）和行为（脚本）分开，并尝试将三者之间的交互保持在绝对最小值。也就是说，确保文档和模板仅包含 HTML 和 HTML 仅服务于结构目的。将所有展示性的东西都变成风格工作表，以及所有行为到脚本中。此外，通过链接尽可能少的样式来保持接触面积尽可能小尽可能从文档和模板中获取工作表和脚本。将结构与表现从行为分开对于维护原因。更改 HTML 文档和模板而不是更新样式表和脚本。

<!-- Not recommended -->
<!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>


<!-- Recommended -->
<!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）时，无需使用实体引用，如：—, ”, 或者 &#x263a。唯一的例外适用于在 HTML 中具有特殊含义的字符（如 <和 & ）以及控制或“不可见”字符（如无间断空格）。

<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- Recommended -->
The currency symbol for the Euro is “€”.

3.1.7、可选标签

省略可选标记（可选）。为了优化文件大小和可扫描性，可以考虑省略可选的标签。HTML5 规范定义了哪些标签可以省略。这种做法可能需要确定一个宽限期，作为更广泛的指导方针因为它与 Web 开发人员通常所教的内容有很大不同。出于一致性和简单性的原因，最好省略所有可选内容标记，而不仅仅是一个选择。

<!-- Not recommended -->
<!DOCTYPE html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>


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

3.1.8、`type` 属性

省略样式表和脚本的type属性。不要对样式表（除非不使用 CSS）和脚本使用type属性（除非不使用 JavaScript）。在这些上下文中指定type text/css text/javascript 属性不是必需的，因为 HTML5 暗示了这一点和作为默认值。即使对于较旧的浏览器，也可以安全地完成此操作。

<!-- Not recommended -->
<link rel="stylesheet" href="https://www.google.com/css/maia.css"
    type="text/css">
<!-- Recommended -->
<link rel="stylesheet" href="https://www.google.com/css/maia.css">

<!-- Not recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"
    type="text/javascript"></script>
<!-- Recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>

3.1.9、`id` 属性

避免不必要的 id 属性。首选用于样式设置class属性和用于脚本编写data属性。在严格需要 id 属性的地方，总要在其值中包含一个连字符，以确保它不符合 JavaScript 标识符语法，例如，使用 user-profile 而不是仅仅使用 profile 或 userProfile。

当一个元素具有 id 属性时，浏览器会将该id属性作为全局 window 原型上的命名属性提供，这可能会导致意外的行为。虽然包含连字符的id属性值仍然可以作为属性名称使用，但这些不能作为全局JavaScript 变量引用。

<!-- Not recommended: `window.userProfile` will resolve to reference the <div> node -->
<div id="userProfile"></div>


<!-- Recommended: `id` attribute is required and its value includes a hyphen -->
<div aria-describedby="user-profile">
  …
  <div id="user-profile"></div>
  …
</div>

3.2、HTML 格式规则

3.2.1、常规格式

对每个块、列表或表元素使用换行符，并缩进每个此类元素子元素。每个display与元素的样式无关（因为 CSS 允许元素假定属性的不同角色），将每个块、列表或表元素在新行上。此外，如果它们是块、列表或表元素的子元素，请缩进它们。

如果您遇到列表项之间的空白问题，那么将所有 li 元素放在一行中是可接受的。建议 linter 发出警告而不是错误。

3.2.2、HTML 换行

断开长行（可选）。虽然HTML没有列限制的建议，但如果可以显著提高可读性，您可能需要考虑换行。在换行时，每行的延续行都应该缩进，以便区分换行属性和子元素。最好通过自动代码格式化工具在项目内一致地换行。

3.2.3、HTML 引号

引用属性值时，请使用双引号。使用双引号("") 而不是单引号('') 包围属性值。

<!-- Not recommended -->
<a class='maia-button maia-button-secondary'>Sign in</a>


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

4、CSS

4.1、样式规则

4.1.1、CSS 有效性

尽可能使用有效的 CSS。除非处理 CSS 验证器错误或需要专有语法，否则请使用有效的 CSS 代码。使用W3C CSS验证器等工具进行测试。

使用有效的CSS是一个可衡量的基本质量属性，它允许我们找出可能没有任何效果的CSS代码并将其删除，同时确保CSS的正确使用。

4.1.2、类命名

使用有意义或通用的类名。不要使用表现性或者隐晦的名称，而应该使用反映元素目的或者通用的类名。具体且反映元素用途的名称应为首选，因为这些是最容易理解的，也是最不可能改变的。

通用名称只是那些没有特定含义或与同级元素含义不同的元素的备用名称。它们通常被用作“助手”。使用功能名称或通用名称可以减少不必要的文档或模板更改的可能性。

/* Not recommended: meaningless */
.yee-1901 {}

/* Not recommended: presentational */
.button-green {}
.clear {}


/* Recommended: specific */
.gallery {}
.login {}
.video {}

/* Recommended: generic */
.aux {}
.alt {}

4.1.3、类名样式

使用尽可能短但必要的类名。尝试传达课程的内容，同时尽可能简短。以这种方式使用类名有助于提高可接受的可理解性和代码效率。

/* Not recommended */
.navigation {}
.atr {}


/* Recommended */
.nav {}
.author {}

4.1.4、类名分隔符

用连字符分隔类名中的单词。不要用任何字符连接选择器中的单词和缩写（包括根本没有）除了连字符，以提高理解性和可扫描性。

/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}

/* Not recommended: uses underscore instead of hyphen */
.error_status {}


/* Recommended */
.video-id {}
.ads-sample {}

4.1.5、前缀

具有特定于应用程序的前缀的前缀选择器（可选）。在大型项目中，以及嵌入到其他项目或外部站点使用前缀（作为命名空间）作为类名。使用简短、独特的标识符后跟破折号。使用命名空间有助于防止命名冲突，并可以进行维护更容易，例如在搜索和替换操作中。

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

4.1.6、类型选择器

避免使用类型选择器限定类名。除非必要（例如，使用帮助程序类），否则不要在与类结合。出于性能原因，避免使用不必要的祖先选择器是有用的。

/* Not recommended */
ul.example {}
div.error {}


/* Recommended */
.example {}
.error {}

4.1.7、ID 选择器

避免使用 ID 选择器。ID 属性在整个页面中应该是唯一的，即当一个页面包含许多由许多人处理的许多组件时，很难保证不同的工程师。在所有情况下都应首选类选择器。

4.1.8、简写属性

尽可能使用简写属性。CSS 提供了各种缩写属性（如 font），这些属性在可能的情况下应始终使用，即使在只显式设置一个值的情况下也应如此。使用缩写属性对于代码效率和可理解性是有用的。

/* Not recommended */
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;




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

4.1.9、0 和单位

除非需要，否则省略“0”值后的单位规格。

4.1.10、十六进制表示法

尽可能使用 3 个字符的十六进制表示法。对于允许的颜色值，3 个字符的十六进制表示法更短，并且更简洁。

/* Not recommended */
color: #eebbcc;



/* Recommended */
color: #ebc;

4.1.11、重要声明

避免使用 !important 声明。这些声明破坏了 CSS 的自然级联，使得推理和组合样式变得困难。应使用选择器特异性来覆盖属性。

4.2、CSS 格式规则

4.2.1、按字母顺序排列声明

按字母顺序排列声明（可选）。在项目中一致地对声明进行排序。在没有工具的情况下自动执行并强制执行一致的排序顺序，请考虑将声明放入按字母顺序排列，以便以易于的方式实现一致的代码学习、记忆和手动维护。

出于排序目的，请忽略特定于供应商的前缀。但是，多个特定于供应商的某个 CSS 属性的前缀应保持排序（例如 -moz 前缀位于 -webkit 之前）。

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、在每次声明后使用分号

在每次声明后使用分号。出于一致性和可扩展性的原因，每个声明都以分号结束。

/* Not recommended */
.test {
  display: block;
  height: 100px
}




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

4.2.4、在属性名称的冒号后使用空格

为了保持一致性，请始终在属性和值之间使用一个空格（但属性和冒号之间不要有空格）。

/* Not recommended */
h3 {
  font-weight:bold;
}
/* Recommended */
h3 {
  font-weight: bold;
}

4.2.5、声明块分离

在最后一个选择器和声明块之间使用空格。始终在最后一个选择器和开始声明块的左大括号之间使用单个空格。左括号应该与给定规则中的最后一个选择器位于同一行。

/* Not recommended: missing space */
.video{
  margin-top: 1em;
}

/* Not recommended: unnecessary line break */
.video
{
  margin-top: 1em;
}
/* Recommended */
.video {
  margin-top: 1em;
}

4.2.6、选择器和声明分离

用换行分隔选择器和声明。始终为每个选择器和声明启动一个新行。

/* Not recommended */
a:focus, a:active {
  position: relative; top: 1px;
}
/* Recommended */
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 引号

对属性使用单引号（''）而不是双引号（"" 选择器和属性值。不要在 URI 值（url()）中使用引号。

异常：如果您确实需要使用@charset规则，则必须使用双引号，不允许使用单引号。

/* Not recommended */
@import url("https://www.google.com/css/maia.css");

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



/* Recommended */
@import url(https://www.google.com/css/maia.css);

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

4.3、CSS Meta规则

4.3.1、章节注释

按节注释对节进行分组（可选）。如果可能，请使用注释将样式表部分组合在一起。分开带有新行的部分。

/* Header */

.adw-header {}

/* Footer */

.adw-footer {}

/* Gallery */

.adw-gallery {}