AllMobilize HTML/CSS Style Guide


HTML/CSS 通用规则

编码规则

省略外链资源 URL 协议部分

省略外链资源(图片及其它媒体资源)URL 中的 http / https 协议,使 URL 成为相对地址,避免 Mixed Content 问题,减小文件字节数。

其它协议(ftp 等)的 URL 不省略。

<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
<!-- Not recommended -->
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
/* Recommended */
.example {
  background: url(//www.google.com/images/example);
}
/* Not recommended */
.example {
  background: url(http://www.google.com/images/example);
}

在同一网站中,推荐使用相对路径链接资源,并避免使用层级过深的文件夹,以提高文件查找效率、减小文件体积

代码格式

缩进

CSS(包括 Less 等扩展语言)中缩进 2 个空格(因模板、Less 等嵌套问题,将代码缩进定为两个空格,避免代码过长)。

不要使用 Tab 或者 Tab、空格混搭(大多编辑器都支持把 Tab 定义为希望的空格数)。

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

一律使用小写字母

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

<!-- Not recommended -->
<A HREF="/">Home</A>
/* Recommended */
color: #e5e5e5;

/* Not recommended */
color: #E5E5E5;

删除行尾空格

元数据规则

文件编码

使用不带 BOM 的 UTF-8 编码。

<meta charset="UTF-8">

注释

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

用注释来解释代码:它包括什么,它的目的是什么,它能做什么,为什么使用这个解决方案,还是说只是因为个人偏好?

(本规则根据实际项目而定,主要取决于项目的复杂程度。)

未完成条目

TODO 标记待办事项和活动的条目。

<!-- TODO(john.doe): revisit centering -->
<center>Test</center>

<!-- TODO: remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>
/* TODO: remove IE hacks */
.nav {
  _width: 1%;
}

HTML 风格指南

编码规则

文档类型(DTD)使用 HTML5

<!DOCTYPE html>

语言属性

根据 HTML5 规范:

强烈建议为 html 元素指定 lang 属性,从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音,有助于翻译工具确定其翻译时所应遵守的规则等等。

更多关于 lang 属性的知识可以从此规范中了解。

这里列出了语言代码表

IE 兼容模式设置为 Edge

IE 支持通过 <meta> 标签来设置渲染前页面所应该采用的 IE 版本。除非有特殊需求,否则最好是设置为 Edge

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

更多细节参考此文

HTML 有效性

编写有效的 HTML 代码,能通过代码校验工具验证。使用符合 HTML5 规范的标签,不允许使用废弃的标签,如 <font><center>等。

<!-- Recommended -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</title>
</head>
<body>
  <article>This is only a test.</article>
</body>
</html>

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

语义化

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

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

多媒体内容提供后备方案

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

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

关注分离:结构、表现、行为分离。

严格保持结构 (标记),表现 (样式),和行为 (脚本)分离, 并尽量让三者之间的交互保持在最低限度。

关注分离对于可维护性至关重要,修改 HTML(结构)要比修改样式、脚本花费更多成本。

<!-- 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>
<p>It’s awesome!</p>

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

不要用 HTML 实体

使用 UTF-8 作为文件编码时,不需要使用 HTML 实体引用,如&mdash;&rdquo;&#x263a;

在 HTML 文档中具有特殊含义的字符(如 <&)例外,控制或不可见字符也例外(如不换行空格)。

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

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

保留可选标签,保持结构完整性

HTML5 规范定义了一些标签可以省略,以保持代码简洁性。但我们要求保持结构的完整,不省略可省标签,闭合所有元素,以避免不同浏览器环境下不可预知的问题出现。

<!-- Recommended -->
<!DOCTYPE html>
<html>
<head>
  <title>Spending money, spending bytes</title>
</head>
<body>
  <p>Sic.</p>
  <img src="xxx.jpg" alt="xxx" />
</body>
</html>

<!-- Not Recommended -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.
<img src="xxx" >

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

使用 CSS 的样式表、使用 JavaScript 的脚本都不需要添加 type 属性。HTML5 默认按照 text/csstext/javascript 解析,兼容较老的浏览器。

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

<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
type="text/css">
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

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

HTML 属性顺序

HTML 属性应当按照以下给出的顺序依次排列,确保代码的易读性。

Class 用于标识高度可复用组件,因此应该排在首位。id 用于标识具体组件,排在第二位。

布尔值属性

HTML5 规范中 disabledcheckedselected 等属性不用设置值(via)。

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

如果非要赋值,不要使用 truefalse,值必须是空字符串或属性的规范名称,且不要在末尾添加空格。

<input type='checkbox' checked name=cheese disabled="disabled">

/* or */

<input type='checkbox' checked name=cheese disabled="">

JavaScript 生成的标签

通过 JavaScript 生成的标签让内容变得不易查找、编辑,并且降低性能。能避免时尽量避免。

其他细节

HTML 代码格式

基本格式

每个块级、列表、表格元素单独占一行,每个子元素都相对父元素缩进。

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

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

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

纯文本在 HTML 标签结束之前不要换行

表格

恰当地使用 <thead>, <tfoot>, <tbody>, <th> 标签(注意:出于速度考虑,<tfoot> 应放在 <tbody>,以便在所有表格数据渲染完成之前显示 <tfoot>)。

<table summary="This is a chart of invoices for 2011.">
  <thead>
  <tr>
    <th scope="col">Table header 1</th>
    <th scope="col">Table header 2</th>
  </tr>
  </thead>
  <tfoot>
  <tr>
    <td>Table footer 1</td>
    <td>Table footer 2</td>
  </tr>
  </tfoot>
  <tbody>
  <tr>
    <td>Table data 1</td>
    <td>Table data 2</td>
  </tr>
  </tbody>
</table>

HTML 属性值使用双引号

不要省略属性值的引号,应始终添加双引号。

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

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

CSS 风格指南

编码规则

CSS 代码有效性。

尽量标准定义的、有效的 CSS 代码,最终的结果应该能通过 CSS 校验器校验(具体项目中视目标平台而定,不盲目追求通过代码校验)。

不要使用 @import

<link> 相比,@import 要慢很多,不光增加额外的请求数,还会导致不可预料的问题。

替代办法:

参考 don’t use @import

ID、Class 命名

ID、Class 使用语义化、通用的命名方式。

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

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


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

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

ID、Class 命名风格

ID 和 Class 的名称应尽量简短,但应注意保留可读、可辨识性。

/* Recommended */
#nav {} /* 简洁、可辨识的简写 */
.author {} /* 本身比较短,可辨识 */

/* Not recommended */
#navigation {} /* 太长,可以精简 */
.atr {} /* 不可读,无法辨识 */

避免元素选择器和 ID、Class 叠加使用

出于性能考量,在没有必要的情况下避免元素选择器叠加 ID、Class 使用。

元素选择器和 ID、Class 混合使用也违反 关注分离 原则。如果HTML标签修改了,就要再去修改 CSS 代码,不利于后期维护。

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

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

使用属性简写

使用简写可以提高代码执行效率和易读性。

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

/* Not recommended */
.el {
  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;
}

大部分情况下,不需要为简写形式的属性声明指定所有值。例如,h1-h6 元素只需要设置上、下边距(margin)的值,因此,一般只需覆盖这两个值就可以。 过度使用简写形式会对属性值带来不必要的覆盖从而引起意外的副作用。

常见的滥用简写属性声明的情况如下:

/* Recommended */
.element {
  margin-bottom: 10px;
  background-color: red;
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

/* Not recommended */
.element {
  margin: 0 0 10px; /* 只需要设置下边距而已 */
  background: red; /* 只需要设置背景颜色而已 */
  border-radius: 3px 3px 0 0;
}

参考链接

属性值为 0 时省略单位

margin: 0;
padding: 0;

省略小数点前面的 0

font-size: .8rem;

使用 rem 作为字号、长度单位

使用 px对可访性会造成一定的问题,em 则随着上下文不断变化,计算较为繁杂。

line-height 不加单位

需要精确控制的场景除外。

使用十六进制颜色编码(rgba()除外)

简写可简写的十六进制颜色值

/* Recommended */
color: #ebc;

/* Not recommended */
color: #eebbcc;

根据项目在 ID、Class 前面加上特定前缀(命名空间)

命名空间可以防止命名冲突,方便维护(查找和替换)。

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

使用连字符 - 作为 ID、Class 名称界定符

CSS 中不要驼峰命名法和下划线。

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

/* Not recommended */
.demoimage {} /* 没有分割 `demo` 和 `image` */
.error_status {} /* 使用下划线链接 */
.errorStatus {} /* 使用驼峰式命名 */

元素在页面中仅仅出现一次的,应该使用 ID,否则使用 Class。

尽量避免 Hacks

面向现代浏览器编写样式,针对过时浏览器的 Hack 可以放在单独的样式表中并使用条件注释引入。

移动开发针对 IE10+ 及其他现代浏览器,移除针对老版本 IE 的 Hack。

Less / SCSS 编写

CSS 代码格式

属性声明顺序

推荐的样式编写顺序:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual

由于定位(positioning)可以从正常的文档流中移除元素,并且还能覆盖盒模型(box model)相关的样式,因此排在首位。盒模型决定了组件的尺寸和位置,因此排在第二位。

其他属性只是影响组件的内部(inside)或者是不影响前两组属性,因此排在后面。

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

链接的样式请严格按照如下顺序添加:

a:link -> a:visited -> a:hover -> a:active(LoVeHAte)

参考:

代码块缩进

缩进花括号({})之间的代码块

@media screen {

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

}

声明的最后一行仍然添加分号

代码压缩由部署工具完成,编写源代码时应该保持每一行代码的完整性。

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

/* Not recommended */
.test {
  display: block;
  height: 100px /* 这一行没有分号 */
}

空格使用

/* Recommended */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

/* Not recommended */

.selector{ /* 选择符和左花括号之间没有添加空格*/
  padding:15px; /* 冒号和值之间没有空格 */
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5); /* 颜色值不加空格 */
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF; /* 逗号分隔的属性值应该添加空格 */
}

带前缀的属性

当使用特定厂商的带有前缀的属性时,通过缩进的方式,让每个属性的值在垂直方向对齐,这样便于多行编辑。

/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

声明块分隔

最后一个选择器和起始花括号在一行,并用一个空格分隔。

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

/* Not recommended: missing space */
#video{ /* 选择器和花括号中间没有空格 */
  margin-top: 1em;
}

/* Not recommended: unnecessary line break */
#video
{ /* 最后一个选择器和花括号之间换行了 */
  margin-top: 1em;
}

选择符、声明单独成行

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

a:focus,
a:active {
  position: relative;
  top: 1px;
}

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

规则之间使用一空行分隔

html {
  background: #fff;
}

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

闭合花括号单独成行

/* Recommended */
h2 {
  font-size: 1.8rem;
}

/* Not recommended */
h2 {
  font-size: 1.8rem;}

引号使用

url() 添加双引号。属性选择符、属性值使用双引号

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

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

.selector[type="text"] {

}

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

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

参考链接

字体名称

字体名称请映射成对应的英文名,例如:黑体(SimHei) 、宋体(SimSun) 、微软雅黑(Microsoft Yahei)。

如果字体名称中有空格,则必须加引号

CSS 元数据规则

按组编写注释

组与组之间空一行,注释与对应组之间不空行(视具体情况约定)。

/* Header */
#adw-header {
}


/* Footer */
#adw-footer {
}


/* Gallery */
.adw-gallery {
}

参考 EditorConfig

# editorconfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
trim_trailing_whitespace = true
insert_final_newline = true

参考链接

Revision: 2014.10.29