静态资源（html、css、图片）开发规范

[TOC]

一. 文档背景

1. 目的

使页面重构工作更系统化、专业化。
减低团队成员合作开发过程中的沟通成本，提高团队协作效率。
提高项目中代码的可维护性、可复用性。
实现快速、高效、高质量输出页面。

2. 基本规则

符合web标准，能通过W3C标准验证。
符合SEO规范。
结构、表现、行为三者分离。
HTML语义化。
可扩展性。
可维护性。
最大限度性能优化。

3. 适用范围

本文档适用于所有html页面重构工作，阅读对象为前端成员；

二. CSS开发规范

1. 文件引用

一律使用link的方式调用外部样式

不允许在页面中使用 <style> 块；
不允许在 <style> 块中使用 @import；
不允许使用 style 属性写行内样式。

尽量不要使用 @import

与 <link> 标签相比，@import 指令要慢很多，不光增加了额外的请求次数，还会导致不可预料的问题。替代办法有以下几种：

使用多个 <link> 元素；
通过 Sass 或 Less 类似的 CSS 预处理器将多个 CSS 文件编译为一个文件；
通过 Rails、Jekyll 或其他系统中提供过 CSS 文件合并功能；

一般情况下，在页面中只允许使用 <link /> 标签来引用CSS文件。

2. 编码

编码统一为UTF-8，保持CSS文件编码与页面编码一致；

3. 命名

3.1 组成元素

命名必须由单词、中划线①或数字组成；

只能出现小写字母、数字和连字符”-”，首字符必须为英文字母（例如：.btn 和 .btn-danger）,不能为纯数字。
名称应当尽可能短，并且意义明确。采用《前缀+连字符“-”+功能》的形式，尽量避免在一级类目中定义不带前缀的class（如：.abc），容易造成样式冲突;
避免过度任意的简写；使用有意义、有组织或目的明确的名称。.btn 代表 button，但是 .a 不能表达任何意思。
子类基于最近的父 class 或基本（base） class 作为新 class 的前缀。
使用 .js-前缀来标识行为（与样式相对，为js预留钩子），并且不要将这些 class 包含到 CSS 文件中。
scss中的变量、函数、混合、placeholder采用驼峰式命名。

CSS元素名称以及id和类名的命名也是区分大小写的（属性和值不区分）

① 我们使用中划线 “-” 作为连接字符，而不是下划线 “_”。

不推荐：
.xiangqing { sRules; } .news_list { sRules; } .zhuti { sRules; }

推荐：
.detail { sRules; } .news-list { sRules; } .topic { sRules; }

3.2 词汇规范

不依据表现形式来命名；可根据内容、功能、模块来命名。

不推荐：
left, right, center, red, black

推荐：
nav, aside, news, type, search

3.3 缩写规范

为保证缩写后还能较为清晰保持原单词所能表述的意思；使用业界熟知的或者约定的缩写方式。

不推荐：
navigation => navi
header => head
description => des

推荐：
navigation => nav
header => hd
description => desc

3.4 前缀规范

前缀	说明	示例
ea-	全局通用样式命名，前缀ea带有企业特色简称，一旦修改将影响全站样式	ea-mod
m-	模块命名方式	m-detail
ui-	组件命名方式	ui-selector
js-	所有用于纯交互的命名，不涉及任何样式规则。JSer拥有全部定义权限	js-switch

选择器必须是以某个前缀开头
因为这样将给我们带来不可预知的管理麻烦以及沉重的历史包袱。你永远也不会知道哪些样式名已经被用掉了，如果你是一个新人，你可能会遭遇，你每定义个样式名，都有同名的样式已存在，然后你只能是换样式名或者覆盖规则。
js- 这种级别的className完全交由JSer自定义，但是命名的规则也可以保持跟重构一致，比如说不能使用拼音之类的
所有的选择器必须是以 ea-, m-, ui- 等有前缀的选择符开头的，意思就是说所有的规则都必须在某个相对的作用域下才生效，尽可能减少全局污染。

不推荐：
.info { sRules; } .current { sRules; } .news { sRules; }

推荐：
.m-detail .info { sRules; } .m-detail .current { sRules; } .m-detail .news { sRules; }

4. 编写规范

4.1 书写格式

不要使用*通配符，因为通配符就是将页面中的所有html标签都渲染一遍，很占用系统资源。
不要在 rgb()、rgba()、hsl()、hsla() 或 rect() 值的内部的逗号后面插入空格。这样利于从多个属性值（既加逗号也加空格）中区分多个颜色值（只加逗号，不加空格）。
为选择器中的属性添加双引号，例如，input[type=”text”]。只有在某些情况下是可选的，但是，为了代码的一致性，建议都加上双引号。
选择器与大括号之间、分号之后、逗号之后保留一个空格；
所有规则需换行；
多组选择器之间需换行;
使用 soft tab缩进（4个空格）;

4.2 属性书写顺序

1. 遵循先布局后内容的顺序：布局定位属性 → 盒模型属性 → 文本属性 → 其他属性
此条可根据自身习惯书写, 但尽量保证同类属性写在一起

属性列举:

布局定位属性: float（包括clear）、position（top,right,bottom,left）、z-index(层叠顺序)、display、overflow等；
盒模型属性: width、height、background、border;
文本属性：font、color、text-align、text-decoration、text-indent等；
其他属性: list-style(列表样式)、vertical-vlign、cursor、zoom 等.

所列出的这些属性只是最常用到的, 并不代表全部;

2. 组概念
拿上例的代码来说，如果我们还需要进行定位及堆叠，规则我们可以改成如下：

.g-box {
    display: block;
    position: relative;
    z-index: 2;
    top: 10px;
    left: 100px;
    float: left;
    width: 500px;
    height: 200px;
    margin: 10px;
    padding: 10px;
    border: 10px solid;
    background: #aaa;
    color: #000;
    font: 14px/1.5 sans-serif;
}

从代码中可以看到，我们直接将z-index, top, left 紧跟在 position 之后，因为这几个属性其实是一组的，如果去掉position，则后3条属性规则都将失效。

3. 私有属性在前标准属性在后

.g-box {
    -webkit-box-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
    -moz-box-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
    -o-box-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
    box-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
}

当有一天你的浏览器升级后，可能不再支持私有写法，那么这时写在后面的标准写法将生效，避免无法向后兼容的情况发生。

4.3 属性缩写与分拆

无继承关系时，使用缩写

不推荐：

body {
    margin-top: 10px;
    margin-right: 10px;
    margin-bottom: 10px;
    margin-left: 10px;
}

推荐：

body {
    margin: 10px;
}

存在继承关系时，使用分拆方式

不推荐：

.m-detail {
    font: bold 12px/1.5 arial, sans-serif;
}
.m-detail .info {
    font: normal 14px/1.5 arial, sans-serif;
}

要避免错误的覆盖：

.m-detail .info {
    font: 14px sans;
}

如果你只是想改字号和字体，然后写成了上面这样，这是错误的写法，因为 font 复合属性里的其他属性将会被重置为 user agent 的默认值，比如 font-weight 就会被重置为 normal。
推荐：

.m-detail {
    font: bold 12px/1.5 arial, sans-serif;
}
.m-detail .info {
    font-weight: normal;
    font-size: 14px;
}

在存在继承关系的情况下，只将需要变更的属性重定义，不进行缩写，避免不需要的重写的属性被覆盖定义

根据规则条数选择缩写和拆分

不推荐：

.m-detail {
    border-width: 1px;
    border-style: solid;
    border-color: #000 #000 #f00;
}

推荐：

.m-detail {
    border: 1px solid #000;
    border-bottom-color: #f00;
}

4.4 id与class

id是唯一的并是父级的, class是可以重复的并是子级的, 所以id仅使用在大的模块上, class可用在重复使用率高及子级中;
原则上重构工程师只允许使用class，把id留给js；

4.5 颜色值写法

将所有的颜色值小写；16进制颜色代码缩写至3位。

不推荐：

body {
    background-color: #FF0000;
}

推荐：

body {
    background-color: #f00;
}

4.6 规则与分号

每条规则结束后都必须加上分号;

不推荐：

body {
    margin: 0;
    padding: 0;
    font-size: 14px
}

推荐：

body {
    margin: 0;
    padding: 0;
    font-size: 14px;
}

4.7 0与单位

如果属性值为0，则不需要为0加单位

不推荐：

body {
    margin: 0px;
    padding: 0px;
}

推荐：

body {
    margin: 0;
    padding: 0;
}

4.8 0与小数

如果是0开始的小数，前面的0可以省略不写

不推荐：

body {
    opacity: 0.6;
    text-shadow: 1px 1px 5px rgba(0, 0, 0, 0.5);
}

推荐：

body {
    opacity: .6;
    text-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
}

4.9 Table表格

使用<table>时(尽量避免使用), 请不要用 width、 height、cellspacing、cellpadding 等table属性直接定义表现, 应尽可能的利用table自身私有属性分离结构与表现;如:thead,tr,th,td,tbody,tfoot,colgroup,scope;

cellspaing及cellpadding的css控制方法:

table {
    border: 0;
    margin: 0;
    border-collapse: collapse;
    border-spacing: 0;
}
table th, table td { padding: 0; }

4.10 h1 到 h6的定义

应遵循从大到小的原则，体现文档的结构，并有利于搜索引擎的查询。

4.11 去掉url中引用资源的引号

不要在url()里对引用资源加引号
不推荐：

body {
    background-image: url("sprites.png");
}
@import url("global.css");

推荐：

body {
    background-image: url(sprites.png);
}
@import url(global.css);

5. CSS规避

a) 通过从属写法规避命名;

示例:

<div id="mainnav">
    <div class="firstnav">…</div>
</div>

样式写法: #mainnav .firstnav{……}

b) 取父级元素id/class命名部分命名;

示例:

<div id="mainnav">
    <div class="main-firstnav">…</div>
</div>

样式写法:.main-firstnav{……}

c) 避免直接定义行内元素样式（span、a、em、i、img、input等），而造成标签污染

不推荐：

<div class="box">
    <span>2010-09-15</span>
</div>
.box span {
    color: red;
}

推荐：

<div class="box">
    <span class="datetime">2010-09-15</span>
</div>
.box span.datetime {
    color: red;
}

6. 注释规范

保持注释内容与星号之间有一个空格的距离

普通注释（单行）

/* 普通注释 */

区块注释

/**
 * 模块: m-detail
 * 描述：酒店详情模块
 * 应用：page detail, info and etc...etc
 */

有特殊作用的规则一定要有注释说明，应用了高级技巧的地方一定要注释说明

7. hack规范

尽可能的减少对Hack的使用和依赖，如果在项目中对Hack的使用太多太复杂，对项目的维护将是一个巨大的挑战；
使用其它的解决方案代替Hack思路；

如果非Hack不可，选择稳定且常用并易于理解的。

.test {
  color: #000;       /* For all */
  color: #111\9;     /* For all IE */
  color: #222\0;     /* For IE8 and later, Opera without Webkit */
  color: #333\9\0;   /* For IE8 and later */
  color: #444\0/;    /* For IE8 and later */
  *color: #666;      /* For IE7 and earlier */
  _color: #777;      /* For IE6 and earlier */
}

严谨且长期的项目，针对IE可以使用条件注释作为预留Hack或者在当前使用

IE条件注释语法：

<!--[if <keywords>? IE <version>?]>
<link rel="stylesheet" href="*.css" />
<![endif]-->

语法说明：

if条件共包含6种选择方式：是否、大于、大于或等于、小于、小于或等于、非指定版本
是否：指定是否IE或IE某个版本。关键字：空
大于：选择大于指定版本的IE版本。关键字：gt（greater than）
大于或等于：选择大于或等于指定版本的IE版本。关键字：gte（greater than or equal）
小于：选择小于指定版本的IE版本。关键字：lt（less than）
小于或等于：选择小于或等于指定版本的IE版本。关键字：lte（less than or equal）
非指定版本：选择除指定版本外的所有IE版本。关键字：!

目前的常用IE版本为6.0及以上，推荐酌情忽略低版本，把精力花在为使用高级浏览器的用户提供更好的体验上，另从IE10开始已无此特性

8. 避免低效率选择器

1. 避免类型选择器;

不允许：

div#doc { sRules; }
li.first { sRules; }

应该：

#doc { sRules; }
.first { sRules; }

2. CSS选择器是由右到左进行解析的，所以 div#doc 本身并不会比 #doc 更快;

3. 避免多id选择器;
不允许：

#xxx #yyy { sRules; }

应该：

#yyy { sRules; }

9. 模块化

每个模块必须是一个独立的样式文件，文件名与模块名一致；
模块样式的选择器必须以模块名开头以作范围约定；
假定有一个模块如前文 HTML模块化，那么 m-detail.scss 的写法大致如下：

.m-detail {
    background: #fff;
    color: #333;
    &-hd {
        padding: 5px 10px;
        background: #eee;
        .title {
            background: #eee;
        }
    }
    &-bd {
        padding: 10px;
        .info {
            font-size: 14px;
            text-indent: 2em;
        }
    }
    &-ft {
        text-align: center;
        .more {
            color: blue;
        }
    }
}

编译之后代码如下：

.m-detail {
    background: #fff;
    color: #333;
}
.m-detail-hd {
    padding: 5px 10px;
    background: #eee;
}
.m-detail-hd .title {
    background: #eee;
}
.m-detail-bd {
    padding: 10px;
}
.m-detail-bd .info {
    font-size: 14px;
    text-indent: 2em;
}
.m-detail-ft {
    text-align: center;
}
.m-detail-ft .more {
    color: blue;
}

任何超过3级的选择器，需要思考是否必要，是否有无歧义的，能唯一命中的更简短的写法

10. iconfont

10.1 unicode引用

unicode是字体在网页端最原始的应用方式，特点是：

兼容性最好，支持ie6+，及所有现代浏览器。
支持按字体的方式去动态调整图标大小，颜色等等。
但是因为是字体，所以不支持多色。只能使用平台里单色的图标，就算项目里有多色图标也会自动去色。

注意：新版iconfont支持多色图标，这些多色图标在unicode模式下将不能使用，如果有需求建议使用symbol的引用方式

unicode使用步骤如下：
第一步：拷贝项目下面生成的font-face

@font-face {font-family: 'iconfont';
    src: url('iconfont.eot');
    src: url('iconfont.eot?#iefix') format('embedded-opentype'),
    url('iconfont.woff') format('woff'),
    url('iconfont.ttf') format('truetype'),
    url('iconfont.svg#iconfont') format('svg');
}

第二步：定义使用iconfont的样式

.iconfont{
    font-family:"iconfont" !important;
    font-size:16px;font-style:normal;
    -webkit-font-smoothing: antialiased;
    -webkit-text-stroke-width: 0.2px;
    -moz-osx-font-smoothing: grayscale;
}

第三步：挑选相应图标并获取字体编码，应用于页面
<i class="iconfont">3</i>

10.2 font-class引用

font-class是unicode使用方式的一种变种，主要是解决unicode书写不直观，语意不明确的问题。
与unicode使用方式相比，具有如下特点：

兼容性良好，支持ie8+，及所有现代浏览器。
相比于unicode语意明确，书写更直观。可以很容易分辨这个icon是什么。
因为使用class来定义图标，所以当要替换图标时，只需要修改class里面的unicode引用。

不过因为本质上还是使用的字体，所以多色图标还是不支持的。

使用步骤如下：

第一步：拷贝项目下面生成的fontclass代码：
//at.alicdn.com/t/font_8d5l8fzk5b87iudi.css

第二步：挑选相应图标并获取类名，应用于页面：
<i class="iconfont icon-xxx"></i>

10.3 symbol引用

这是一种全新的使用方式，应该说这才是未来的主流，也是平台目前推荐的用法。相关介绍可以参考这篇文章这种用法其实是做了一个svg的集合，与上面两种相比具有如下特点：

支持多色图标了，不再受单色限制。
通过一些技巧，支持像字体那样，通过font-size,color来调整样式。
兼容性较差，支持 ie9+,及现代浏览器。

浏览器渲染svg的性能一般，还不如png。

使用步骤如下：

第一步：拷贝项目下面生成的symbol代码：
//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js

第二步：加入通用css代码（引入一次就行）：

<style type="text/css">
    .icon {
       width: 1em; height: 1em;
       vertical-align: -0.15em;
       fill: currentColor;
       overflow: hidden;
    }
</style>

第三步：挑选相应图标并获取类名，应用于页面：

<svg class="icon" aria-hidden="true">
    <use xlink:href="#icon-xxx"></use>
</svg>

11. Sass 中的嵌套

避免非必要的嵌套。这是因为虽然你可以使用嵌套，但是并不意味着应该使用嵌套。只有在必须将样式限制在父元素内（也就是后代选择器），并且存在多个需要嵌套的元素时才使用嵌套。

// bad
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// good
.table > thead > tr {
  > th { … }
  > td { … }
}

三、图片规范

所有图片必须经过一定的压缩和优化才能发布（压缩工具tinypng.com）
图片格式仅限于gif /png/ jpg/svg;
命名全部用小写英文字母,数字, _ 的组合，其中不得包含汉字,空格,特殊字符；
尽量用易懂的词汇, 便于团队其他成员理解; 另, 命名分头尾两部分, 用下划线隔开, 比如ad_left01.gif ,btn_submit.gif;
在保证视觉效果的情况下选择最小的图片格式与图片质量, 以减少加载时间;
尽量避免使用半透明的png图片(若使用, 请参考css规范相关说明);
运用css sprite技术集中小的背景图或图标, 减少页面http请求, 但注意, 请务必在对应的sprite psd源图中划参考线, 并保存至img目录下.

注：测试用图片统一放入images/pic文件夹，只做本地使用，不纳入打包资源。

四、HTML规范

1.HTML5 文档类型
页面统一使用HTML5 文档类型. 代码如下：

<!DOCTYPE html>
<html>...</html>

2.编码
声明方法遵规循HTML5的范. 代码如下：

<meta charset="utf-8">

3.移动设备优先
在移动设备浏览器上，通过为视口（viewport）设置 meta 属性为 user-scalable=no 可以禁用其缩放（zooming）功能。这样禁用缩放功能后，用户只能滚动屏幕，就能让你的网站看上去更像原生应用的感觉。

<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no ">

4.meta视情况添加

<meta name="keywords" content="星链">

该行为页面添加关键字

`<meta name="description" content="星链">`

该行为页面添加页面描述信息

<meta name="apple-mobile-web-app-capable" content="yes">

该行的作用在于删除默认的苹果工具栏和菜单栏。content有两个值yes和no,当我们需要显示工具栏和菜单栏时，这个行meta就不用加了，默认就是显示。

<meta name="format-detection" content="telephone=no">

该行禁止了移动设备自动把数字串转换为电话号码；

5.完整HTML头部声明

<!DOCTYPE html>
    <html>
        <meta charset="utf-8">
        <title>星链</title>
        <meta name="keywords" content="星链">
        <meta name="description" content="星链">
        <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no">
        <meta name="format-detection" content="telephone=no">
    </html>

6.语义化
使用符合语义的标签书写 HTML 文档, 选择恰当的元素表达所需的含义。
如标题根据重要性用h1-h6(同一页面只能有一个h1), 段落标记用p, 列表用li;

7.大小写，属性值
元素的标签和属性名必须小写, 属性值必须加双引号。

8.必须为含有描述性表单元素(input, textarea)添加label标签；
不推荐：

    <div>
        姓名:<input type="text" id="name" name="name">
    </div>

推荐：

    <div>
        <label for="name">姓名: </label>
        <input type="text" id="name">
    </div>

9.充分利用无兼容性问题的html自身标签及减少div嵌套。
不推荐：

    <div class="box">
        <div class="welcome">欢迎访问XXX, 您的用户名是
            <div class="name">用户名</div>
        </div>
    </div>

推荐：

    <div class="box">
        <p>欢迎访问XXX, 您的用户名是<span>用户名</span></p>
    </div> ;