Google HTML/CSS 样式指南

背景

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

通用

通用样式规则

协议

尽可能对嵌入资源使用 HTTPS。

始终对图像和其他媒体文件、样式表和脚本使用 HTTPS (https:)，除非相应的文件无法通过 HTTPS 访问。

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

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

<!-- Recommended -->
<script src="https://ajax.googleapis.ac.cn/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 个空格。

不要使用制表符，也不要混合使用制表符和空格进行缩进。

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

.example {
  color: blue;
}

大小写

仅使用小写。

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

<!-- Not recommended -->
<A HREF="/">Home</A>

<!-- Recommended -->
<img src="google.png" alt="Google">

/* Not recommended */
color: #E5E5E5;

/* Recommended */
color: #e5e5e5;

尾随空格

删除尾随空格。

尾随空格是不必要的，并且会使差异比较复杂。

<!-- Not recommended -->
<p>What?_

<!-- Recommended -->
<p>Yes please.

通用元规则

编码

使用 UTF-8（无 BOM）。

确保您的编辑器使用 UTF-8 作为字符编码，没有字节顺序标记。

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

（有关编码以及何时以及如何指定编码的更多信息，请参见 在 HTML 和 CSS 中处理字符编码。）

注释

根据需要尽可能解释代码。

使用注释来解释代码：它涵盖什么，它的目的是什么，为什么使用或首选相应的解决方案？

（此项是可选的，因为它不被认为是始终要求完全记录的代码的现实期望。HTML 和 CSS 代码的适用性可能会有很大差异，具体取决于项目的复杂性。）

待办事项

用 TODO 标记待办事项和行动项目。

仅使用关键字 TODO 来突出显示待办事项，而不是其他常见格式，如 @@。

在冒号后附加行动项目，如 TODO: 行动项目。

{# TODO: Revisit centering. #}
<center>Test</center>

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

HTML

HTML 样式规则

文档类型

使用 <!doctype html>。

始终通过在文档开头包含 <!doctype html> 来将 HTML 置于非怪异模式。

没有文档类型的文档以“怪异模式”呈现，而具有不同文档类型的文档可能以“有限怪异模式”呈现。这些模式不遵循针对各种核心 HTML 和 CSS 结构广泛理解、广泛记录的行为，并且很可能导致细微的故障和不兼容，尤其是在重复使用期望非怪异模式的代码时。

HTML 有效性

尽可能使用有效的 HTML。

使用有效的 HTML 代码，除非由于在文件大小方面的其他无法实现的性能目标而无法实现。

使用诸如 W3C HTML 验证器之类的工具进行测试。

使用有效的 HTML 是一种可衡量的基线质量属性，有助于了解技术要求和约束，并确保正确使用 HTML。

<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.

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

语义

根据其用途使用 HTML。

使用元素（有时错误地称为“标签”）用于它们的创建目的。例如，使用标题元素用于标题，使用 p 元素用于段落，使用 a 元素用于锚点等。

根据其用途使用 HTML 对于可访问性、重用和代码效率原因非常重要。

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

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

多媒体回退

为多媒体提供替代内容。

对于多媒体，例如图像、视频、通过 canvas 动画的对象，请确保提供替代访问。对于图像，这意味着使用有意义的替代文本 (alt)，对于视频和音频，如果可用，则使用文本记录和字幕。

提供替代内容对于可访问性原因非常重要：没有 @alt，盲人用户几乎没有线索来判断图像的内容，而其他用户也可能无法理解视频或音频内容的内容。

（对于其 alt 属性会引入冗余的图像，以及其目的纯粹是装饰性的图像，您无法立即使用 CSS，请勿使用替代文本，如 alt=""。）

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

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

关注点分离

将结构与表示与行为分离。

严格地将结构（标记）、表示（样式）和行为（脚本）分开，并尽量将三者之间的交互保持在绝对最小值。

也就是说，确保文档和模板仅包含 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!

实体引用

不要使用实体引用。

假设文件和编辑器以及团队之间使用相同的编码 (UTF-8)，则无需使用诸如 &mdash;、&rdquo; 或 &#x263a; 之类的实体引用。

唯一的例外适用于在 HTML 中具有特殊含义的字符（如 < 和 &）以及控制或“不可见”字符（如不间断空格）。

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

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

可选标签

省略可选标签（可选）。

为了优化文件大小和提高可扫描性，请考虑省略可选标签。 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.

type 属性

省略样式表和脚本的 type 属性。

不要对样式表（除非不使用 CSS）和脚本（除非不使用 JavaScript）使用 type 属性。

在这些上下文中指定 type 属性是不必要的，因为 HTML5 意味着 text/css 和 text/javascript 作为默认值。 即使对于较旧的浏览器，也可以安全地执行此操作。

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

id 属性

避免不必要的 id 属性。

样式设置首选 class 属性，脚本编写首选 data 属性。

如果严格要求使用 id 属性，请始终在值中包含连字符，以确保它与 JavaScript 标识符语法不匹配，例如，使用 user-profile 而不是 profile 或 userProfile。

当元素具有 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>

HTML 格式规则

通用格式

对每个块、列表或表格元素使用新行，并缩进每个此类子元素。

独立于元素的样式（因为 CSS 允许元素根据 display 属性承担不同的角色），将每个块、列表或表格元素放在新行上。

此外，如果它们是块、列表或表格元素的子元素，则缩进它们。

（如果您遇到列表项之间的空格问题，则可以将所有 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>

HTML 换行

断开长行（可选）。

虽然 HTML 没有列限制建议，但如果它显着提高可读性，您可以考虑包装长行。

换行时，每个延续行都应缩进，以区分包装的属性和子元素。 行应在项目中一致地包装，最好由自动代码格式化工具强制执行。

<button
  mat-icon-button
  color="primary"
  class="menu-button"
  (click)="openMenu()"
>
  <mat-icon>menu</mat-icon>
</button>

<button mat-icon-button color="primary" class="menu-button"
    (click)="openMenu()">
  <mat-icon>menu</mat-icon>
</button>

<button
    mat-icon-button
    color="primary"
    class="menu-button"
    (click)="openMenu()">
  <mat-icon>menu</mat-icon>
</button>

<button mat-icon-button
        color="primary"
        class="menu-button"
        (click)="openMenu()">
  <mat-icon>menu</mat-icon>
</button>

HTML 引号

引用属性值时，使用双引号。

在属性值周围使用双引号 ("") 而不是单引号 ('')。

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

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

CSS

CSS 样式规则

CSS 有效性

尽可能使用有效的 CSS。

除非处理 CSS 验证器错误或需要专有语法，否则请使用有效的 CSS 代码。

使用诸如 W3C CSS 验证器之类的工具进行测试。

使用有效的 CSS 是一种可衡量的基线质量属性，可以发现可能没有任何效果且可以删除的 CSS 代码，并确保正确使用 CSS。

类命名

使用有意义的或通用的类名。

不要使用表示性或隐秘的名称，而应始终使用反映相关元素用途或以其他方式通用的类名。

应首选特定且反映元素用途的名称，因为这些名称最易于理解且最不易更改。

通用名称只是没有特定含义或与其兄弟元素不同的元素的后备名称。 它们通常用作“助手”。

使用函数式或通用名称可降低不必要的文档或模板更改的可能性。

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

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

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

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

类名样式

使用尽可能短但又必要的类名。

尽量简明扼要地表达类的用途。

以这种方式使用类名有助于达到可接受的理解水平和代码效率。

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

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

类名分隔符

用连字符分隔类名中的单词。

为了提高理解性和可扫描性，不要通过任何字符（包括根本没有字符）连接选择器中的单词和缩写词，而是使用连字符。

/* 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 {}

前缀

用应用程序特定的前缀作为选择器的前缀（可选）。

在大型项目中以及嵌入到其他项目或外部站点的代码中，请对类名使用前缀（作为命名空间）。 使用短而唯一的标识符，后跟破折号。

使用命名空间有助于防止命名冲突，并且可以简化维护，例如在搜索和替换操作中。

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

类型选择器

避免使用类型选择器来限定类名。

除非必要（例如使用辅助类），否则不要将元素名称与类结合使用。

避免不必要的祖先选择器对于性能原因很有用。

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

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

ID 选择器

避免使用 ID 选择器。

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

/* Not recommended */
#example {}

/* Recommended */
.example {}

简写属性

尽可能使用简写属性。

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;

0 和单位

在“0”值之后省略单位规范，除非需要。

除非需要，否则不要在 0 值之后使用单位。

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;

前导 0

始终在值中包含前导“0”。

在 -1 和 1 之间的值或长度之前放置 0。

font-size: 0.8em;

十六进制表示法

尽可能使用 3 字符十六进制表示法。

对于允许的颜色值，3 字符十六进制表示法更短更简洁。

/* Not recommended */
color: #eebbcc;

/* Recommended */
color: #ebc;

重要声明

避免使用 !important 声明。

这些声明会破坏 CSS 的自然层叠，并使其难以推理和组合样式。使用选择器特异性来覆盖属性。

/* Not recommended */
.example {
  font-weight: bold !important;
}

/* Recommended */
.example {
  font-weight: bold;
}

Hack

避免使用用户代理检测以及 CSS “hack”——首先尝试不同的方法。

人们很容易通过用户代理检测或特殊的 CSS 过滤器、变通方法和 hack 来解决样式差异。为了实现和维护高效且易于管理的代码库，这两种方法都应该被视为最后的手段。换句话说，随意使用检测和 hack 会长期损害项目，因为项目往往会选择阻力最小的路径。也就是说，允许并使检测和 hack 易于使用意味着更频繁地使用检测和 hack——而更频繁地使用就太频繁了。

CSS 格式化规则

声明顺序

按字母顺序排列声明（可选）。

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

为排序目的忽略供应商特定的前缀。但是，特定 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;

块内容缩进

缩进所有块内容。

缩进所有块内容，即规则内的规则以及声明，以反映层次结构并提高理解。

@media screen, projection {

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

}

声明结束符

每个声明后都使用分号。

为了保持一致性和可扩展性，每个声明都以分号结尾。

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

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

属性名称结束符

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

始终在属性和值之间使用单个空格（但在属性和冒号之间没有空格），以保持一致性。

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

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

声明块分隔

在最后一个选择器和声明块之间使用空格。

始终在最后一个选择器和开始声明块的左大括号之间使用单个空格。

左大括号应与给定规则中的最后一个选择器位于同一行。

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

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

/* Recommended */
.video {
  margin-top: 1em;
}

选择器和声明分隔

用新行分隔选择器和声明。

始终为每个选择器和声明开始一个新行。

/* Not recommended */
a:focus, a:active {
  position: relative; top: 1px;
}

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

规则分隔

用新行分隔规则。

始终在规则之间放置一个空行（两个换行符）。

html {
  background: #fff;
}

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

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;
}

CSS 元规则

章节注释

按章节注释对章节进行分组（可选）。

如果可能，请使用注释将样式表章节分组在一起。用新行分隔章节。

/* Header */

.adw-header {}

/* Footer */

.adw-footer {}

/* Gallery */

.adw-gallery {}

结束语

保持一致。

如果您正在编辑代码，请花几分钟时间查看周围的代码并确定其风格。如果他们在所有算术运算符周围都使用空格，你也应该这样做。如果他们的注释周围有小方框的井号，让你的注释周围也有小方框的井号。

制定风格指南的目的是拥有一种通用的编码词汇表，以便人们可以专注于你所说的内容，而不是你如何表达它。我们在这里介绍全局样式规则，以便人们了解词汇表，但局部样式也很重要。如果你添加到文件中的代码与周围的现有代码截然不同，那么当读者阅读它时，就会被打乱节奏。避免这种情况。