WEB前端规范

1. 规范说明

此为前端开发团队遵循和约定的代码书写规范，意在提高代码的规范性和可维护性。
此规范为参考规范，不全是硬性要求，部分硬性约定见下一条书写规范，统一团队编码规范和风格。让所有代码都是有规可循的，并且能够得到沉淀，减少重复劳动。

1.1 结构说明

-- 项目结构
----|---- CSS文件结构
----|---- JS文件结构

2. 书写规范

2.1 样式与内容分离

2.1.1 项目结构

--- 
 |---- index.html             入口页    
 |---- js/                    JS //具体见JS细化结构                 
 |---- css/                   CSS //具体见CSS细化结构

2.1.2 重构步骤约定

  1. index.html 全部样式附着于 class="xxx" 注： 此时文件中不包含任何一个 id="xxx"
  2. 为上一步书写 CSS style
    [至此重构完成]
  3. 开始书写js交互文件，使用 ID 和 Class 定位被操作句柄
  4. 向 index.html 中需要的地方添加 id="xxx" 及 data-xxx="xxx"
    [至此交互效果完成]

2.1.3 命名规范

  • 文件及文件夹: 全部英文小写字母+数字或连接符"- , _ "，不可出现其他字符
    如：../css/style.css, jquery.1.x.x.js
  • 文件：调用 /libs 文件需包含版本号，压缩文件需包含min关键词，其他插件则可不包含
    如：/libs/jquery.1.9.1.js /libs/modernizr-1.7.min.js fileuploader.js plugins.js
  • ID: 匈牙利命名法 & 小駝峰式命名法
    如：firstName topBoxList footerCopyright
  • Class: [减号连接符]
    如：top-item main-box box-list-item-1
  • 尽量使用语义明确的单词命名，避免 left bottom 等方位性的词语

2.1.4 格式&编码

  • 文本文件： .xxx UTF-8_(无BOM)_ 编码
  • 图片文件： .png (PNG-24) .jpg (压缩率8-12)
  • 动态图片： .gif
  • 压缩文件： .tar.gz .zip

2.2 CSS 细化规范

2.2.1 CSS 文件结构

--- ../css/
 |---- css/libs/reset.css                  CSS reset文件
 |---- … … 
 |---- css/images/                         主 CSS-sprite 图片     
 |---- css/style.css                       主 CSS 样式表
 |---- … … 
 |---- css/images/xxx/sprite.png           xxx 的 CSS-sprite 图片
 |---- css/xxx-style.css                   xxx 的 样式表

2.2.2 CSS(含Less) 文件结构

--- ../css/
 |---- css/libs/reset.less            CSS reset文件
 |---- css/libs/elements.less         Less 函数复用文件
 |---- … … 
 |---- css/images/                         主 CSS-sprite 图片     
 |---- css/style.less                      主样式Less
 |---- css/style.css                       less -> css 自动生成
 |---- … … 
 |---- css/images/xxx/sprite.png           xxx 的 CSS-sprite 图片
 |---- css/xxx-style.less                  xxx 的 Less
 |---- css/xxx-style.css                   less -> css 自动生成

2.2.3 使用Less

在 .less文件头部引入 reset.less & elements.less，之后调用如下属性传参即可，具体使用说明见 -> Lesselements 官方文档

@import "libs/reset.less";  
@import "libs/elements.less";

.gradient
.bw-gradient
.bordered
.drop-shadow
.rounded
.border-radius
.opacity
.transition-duration
.rotation
.scale
.transition
.inner-shadow
.box-shadow
.columns
.translate

2.2.4 CSS reset

CSS reset 文件使用：reset.css 或 reset.less

  • reset文件用于重设各个浏览器的默认样式方案，解决其引起的耦合问题。
  • 也可使用 .clearfix 清除浮动

2.2.5 CSS 注释格式约定

/*
@name: Drop Down Menu
@description: Style of top bar drop down menu.
@require: reset.css
@author: Andy Huang(andyahung@geekpark.net)
*/

其中，@require为可选项

  • CSS换行制表：使用 2 <del>或4</del> 个空格，而非[Tab]
  • 书写格式：
    • CSS名称+冒号+属性
      如：.box1 {float:left;}
    • 建议保留{左侧空格，字体名用\包含
      如：.box1,.box2,.box3 {font-family:Courier,'Courier New';}
    • 避免中文，或使用转义，推荐前者
      如：font-family: "Microsoft YaHei"; font-family:\5fae\8f6f\96c5\9ed1;

2.2.6 CSS各属性的排列顺序：不做硬性要求

如：以下2种顺序均可

.box {
  /* 顺序1 */
  background: none repeat scroll 0 0 transparent;
  bottom: 11px;
  position: relative;
  width: 22px;
  z-index: 33;
}
.box {
  /* 顺序2 */
  z-index: 33;
  width: 22px;
  bottom: 11px;
  background: transparent none repeat scroll 0 0 ;
  position: relative;
}

2.2.7 CSS嵌套规则

/* 推荐嵌套层级 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-nav .ui-list{}
.ui-table .ui-list{}

/* 不推荐 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-list{}
.ui-nav{}

2.2.8 CSS格式化

勿格式化，保留下面这种格式，增加可读性和可维护性，后期后台程序(如：PHP/Python)会将CSS压缩成 一行 输出：

.box{
  /* 勿格式化，增加可读性 */
  background: none repeat scroll 0 0 transparent;
  bottom: 11px;
  position: relative;
  width: 22px;
  z-index: 33;
}

2.3 XHTML 细化规范

2.3.1 HTML 注释格式约定

<!--
@name: Drop Down Menu
@description: Style of top bar drop down menu.
@author: Andy Huang(andyahung@geekpark.net)
-->

<div id="header">
    <div class="xxx">
        <span>HTML行内注释格式</span>
    </div>
</div><!-- #header end-->
  • HTML换行缩进：采用 2 空格

2.3.2 HTML嵌套规则

/* 推荐嵌套层级 */
  <ul class="ui-nav">
    <li class="ui-nav-item"> some text
      <ul class="ui-nav-item-child">
        <li> some text
          <ul class="ui-list">
            <li class="ui-list-item"> some text</li>
          </ul
        ...
       </ul>
    </li>
    <li
    ...
  </ul>

2.3.4 * 第一行统一使用HTML5标准：<!DOCTYPE html>

<!DOCTYPE html>
<html dir="ltr" lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <title>极客公园 | 创新者社区</title>
  <meta name="keywords" content="xxxx, xxx, xxxxx" />
  <meta name="description" content="xxxxxxxxxxxxxxxxxxxx" />

2.3.5 Meta 的使用：（需要根据具体需求按需选择）可参看：cool-head 

<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta http-equiv="Cache-Control" content="max-age=7200" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="alternate" type="application/rss+xml" title="RSS 2.0" href="http://feeds.geekpark.net/" />
<link rel="shortcut icon" href="favicon.ico">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

<script type="text/javascript" src="/js/xxx.js"></script>
<link rel="stylesheet" href="/css/xxx.css">

<script type="text/javascript">
    //Google 统计代码 的位置在离</head>最近的位置
</script>

</head>

  • <img>标签默认缺省格式：<img src="xxx.png" alt="缺省时文字" /> 避免出现[src="" 问题]
  • <a>标签缺省格式：<a href="###" title="链接名称">xxx</> 注：target="_blank" 根据需求决定
  • <a>标签预留链接占位符使用###，参见：[a标签占位符问题]
  • 所有标签需要符合XHTML标准闭合
  • 一律统一标签结尾斜杠的书写形式：<br /> <hr /> 注意之间空格
  • 避免使用已过时标签，如：<b> <u> <i> 而用 <strong> <em>等代替
  • 使用data-xxx来添加自定义数据，如：<input data-xxx="yyy"/>
  • 避免使用style="xxx:xxx;"的内联样式表
  • 特殊符号使用参考HTML 符号实体

2.4 JS 细化规范

2.4.1 JS 文件结构

---/js/
|---- /libs/plugin-1/       使用到的js插件1  
|---- /libs/plugin-2/       使用到的js插件2  
|---- /libs/plugin-3/       使用到的js插件3  
|---- script.js             单独书写的js  
|---- plugins.js            调用的plugins汇总  
|---- juqery-1.9.x.min.js   调用jq库文件
  • JS 换行缩进：采用 4 空格
  • 结束行需添加分号;
  • jQuery变量要求首字符为 $, 私有变量:首字符为_; 尽量避免全局变量.
  • 避免使用 eval()，setTimeOut使用调用函数，考虑重绘，回流 操作对页面影响 参看：reflows，repaints
  • JS调试使用console.log()及console.dir()进行，避免使用弹出框，线上版需要注释所有调试代码
  • JS压缩混淆工具: JS Compressor 如果使用了压缩，需要留 name-src.js在同路径供今后修改使用
2.4.2 jQuery Call
<!-- Grab Google CDN jQuery. fall back to local if necessary -->  
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>  
<script>!window.jQuery && document.write('<script src="js/jquery-1.7.2.min.js"><\/script>')</script>
2.4.3 jQuery Plugin
2.4.4 JSON格式规范

参考JSON Style Guide翻译，原版：Google JSON Style Guide

HTML 细化规范

  • HTML head部分的结构参看：cool-head (摘取必要内容即可)
  • css 文件置于都 头部
  • jQuery 及 Google Analytics引用置于 头部
  • 其他效果js及统计代码 文件置于 尾部
  • HTML 代码尽量过一遍HTML5 验证
  • HTML 占位图片使用 temp.im & placehold.us 图片服务

2.5 Responsive Web 规范

从设计之处就坚持"Mobile First"的理念，在重构页面的时候要灵活采取响应式的解决方案。

2.5.1 响应式实现途径

* 设置 meta viewport 属性

<meta name="viewport" content="width=device-width, initial-scale=1" />

* 引入不同尺寸设备的样式表

<link rel="stylesheet" type="text/css" href="style.css" media="screen, handheld" />
<link rel="stylesheet" type="text/css" href="enhanced.css" media="screen  and (min-width: 40.5em)" />
<!--[if (lt IE 9)&(!IEMobile)]>
<link rel="stylesheet" type="text/css" href="enhanced.css" />
<![endif]-->

* 使用 CSS Media Queries 方法

@media screen and (max-width: 40.5em) {
  .product-img {
    width: auto;
    float: none;
  }
}
@media screen and (max-width: 480px) {
}

* JS控制导航栏在 resize 事件 触发后的可见性，如：

$(w).resize(function(){ //Update dimensions on resize
  sw = document.documentElement.clientWidth;
  sh = document.documentElement.clientHeight;
  checkMobile();
});
//Check if Mobile
function checkMobile() {
  mobile = (sw > breakpoint) ? false : true;
  if (!mobile) { //If Not Mobile
    $('[role="tabpanel"],#nav,#search').show(); //Show full navigation and search
  } else { //Hide 
    if(!$('#nav-anchors a').hasClass('active')) {
      $('#nav,#search').hide(); //Hide full navigation and search
    }
  }
}

2.5.2 响应式解决方案

* 弹性图片

img {
  max-width: 100%;
  height: auto;
  width: auto\9; /* ie8 */
}

* 自适应嵌入媒体

.video embed, .video object, .video iframe {
  width: 100%;
  height: auto;
}

* 禁用iPhone字体自适应功能：

html {
  -webkit-text-size-adjust: none;
}

* 让 IE 9 以下的IE版本支持响应式：

<!--[if lt IE 9]>
  <script src="http://css3-mediaqueries-js.googlecode.com/svn/trunk/css3-mediaqueries.js"></script>
<![endif]-->

2.6 Newletter 制作规范

  • CSS只可使用 内联样式表 ，如：style="margin:0;"
  • 设计之初遵循： 图上无文本，文本后无底纹 的规则
  • 使用 MailChimp HTML Email CSS Fix 参看下文链接
  • 引入 CSS Reset for HTML Email 参看下文链接
  • 使用Table布局而非DIV
  • 所有图片使用IMG标签，如：<img style="style="display:block" "src="" />
  • 可以适当使用占位符spacer.gif
  • 多用<br />换行而非<p>
  • 整体最佳宽度为：550-600px
  • 不使用Javascript
  • 正式发送给用户之前，多次测试

更多细节参考下面链接：
12 Killer Tips and Tricks for Building HTML Email

2.7 生产力工具推荐

2.7.1 for Mac OS

for more app detial check -> IUSETHIS

2.7.1.1 前端相关工具(Mac)
2.7.1.2 其他效率工具
2.7.2.1 前端相关工具(Windows)
2.7.2.2 其他效率工具(Windows)

2.7.3 其他收集

2.8 相关技巧

Wiki page index

2.9 参考数据

涉及到 设计->重构->兼容性->测试 时可参考各浏览器的占用情况
-- updated: 2013/02 - 2013/04 via Google Analytics of GeekPark

<table>
<tbody valign="top"><tr>
<th align="center">总浏览器分布</th>
<th align="center">IE版本分布</th>
<th align="center">移动设备分布</th>
<th align="center">屏幕解决方案</th>
</tr>
<tr>
<td align="left">

<table>
<tbody><tr>
<th align="left">类别</th>
<th align="right">占有率</th>
</tr>
<tr>
<td align="left">Chrome</td>
<td align="right">40.39%</td>
</tr>
<tr>
<td align="left">Internet Explorer</td>
<td align="right">24.86%</td>
</tr>
<tr>
<td align="left">Safari & Safari (in-app)</td>
<td align="right">16.05%</td>
</tr>
<tr>
<td align="left">Android Browser</td>
<td align="right">10.57%</td>
</tr>
<tr>
<td align="left">Firefox</td>
<td align="right">5.99%</td>
</tr>
<tr>
<td align="left">Opera</td>
<td align="right">0.69%</td>
</tr>
<tr>
<td align="left">Opera Mini</td>
<td align="right">0.37%</td>
</tr>
<tr>
<td align="left">Mozilla Compatible Agent</td>
<td align="right">0.14%</td>
</tr>
<tr>
<td align="left">Maxthon</td>
<td align="right">0.13%</td>
</tr>
</tbody></table>
</td>
<td align="right">

<table>
<tbody><tr>
<th align="left">版本号</th>
<th align="right">占有率</th>
</tr>
<tr>
<td align="left">IE 8</td>
<td align="right">60.97%</td>
</tr>
<tr>
<td align="left">IE 9</td>
<td align="right">17.11%</td>
</tr>
<tr>
<td align="left"><em>IE 7</em></td>
<td align="right">8.39%</td>
</tr>
<tr>
<td align="left"><em>IE 6</em></td>
<td align="right">7.63%</td>
</tr>
<tr>
<td align="left">IE 10</td>
<td align="right">5.87%</td>
</tr>
<tr>
<td align="left">IE 4</td>
<td align="right">0.02%</td>
</tr>

</tbody></table>
</td>
<td align="right">

<table>
<tbody><tr>
<th align="left">移动平台</th>
<th align="right">占有率</th>
</tr>
<tr>
<td align="left">iOS</td>
<td align="right">50.39%</td>
</tr>
<tr>
<td align="left">Android</td>
<td align="right">48.05%</td>
</tr>
<tr>
<td align="left">Windows Phone</td>
<td align="right">0.96%</td>
</tr>
<tr>
<td align="left">Nokia</td>
<td align="right">0.33%</td>
</tr>
</tbody></table>
</td>
<td align="right">
<table>
<tbody><tr>
<th align="left">PC & Mac屏幕分辨率</th>
<th align="right">占有率</th>
</tr>
<tr>
<td align="left">1366x768</td>
<td align="right">21.55%</td>
</tr>
<tr>
<td align="left">1440x900</td>
<td align="right">12.70%</td>
</tr>
<tr>
<td align="left">1280x800</td>
<td align="right">9.60%</td>
</tr>
<tr>
<td align="left">1280x1024</td>
<td align="right">6.68%</td>
</tr>
<tr>
<td align="left">320x480</td>
<td align="right">6.38%</td>
</tr>
<tr>
<td align="left">1920x1080</td>
<td align="right">6.27%</td>
</tr>
</tbody></table>
</td>
</tr>
</tbody></table>

使用团队

此规范基于 MIT License 开源，持续更新维护中，可 Star 或 Fork 本项来形成你的规范，请以 创建[issues] 的方式反馈，或发起Pull Request

[src="" 问题]: http://js8.in/555.html "src="" 问题"
[a标签占位符问题]: http://www.v2ex.com/t/48511/ "a标签占位符问题"

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 157,298评论 4赞 360
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 66,701评论 1赞 290
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 107,078评论 0赞 237
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 43,687评论 0赞 202
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 52,018评论 3赞 286
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 40,410评论 1赞 211
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 31,729评论 2赞 310
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 30,412评论 0赞 194
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 34,124评论 1赞 239
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,379评论 2赞 242
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,903评论 1赞 257
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 28,268评论 2赞 251
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 32,894评论 3赞 233
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,014评论 0赞 8
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,770评论 0赞 192
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 35,435评论 2赞 269
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 35,312评论 2赞 260

推荐阅读更多精彩内容

  • web前端规范
    通用规范 tab键用两个空格代替 因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四个空...
    米塔塔阅读 403评论 0赞 7
  • web前端规范
    1：通用规范 tab键用两个空格代替 因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四...
    糖心m阅读 421评论 0赞 1
  • web前端规范
    通用规范 tab键用两个空格代替 因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四个空...
    戈薇薇阅读 455评论 0赞 1
  • web前端规范
    通用规范 tab键用两个空格代替因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四个空格...
    熊猫猫超人阅读 29,867评论 17赞 113
  • 前端面试题整理
    在线阅读 http://interview.poetries.top[http://interview.poetr...
    程序员poetry阅读 113,828评论 24赞 450