前端开发规范
小弟参考网上资料整理的规范文档.
一、 前言
1.1 何为规范
对于某一工程作业或者行为进行定性的信息规定。主要是因为无法精准定量而形成的标准,所以,被称为规范。【百度百科:http://baike.baidu.com/view/113045.htm】
1.2 为何规范
规范并不是一种限制,而是约定,强调团队的一致性;加强团队之间的合作,提高协作效率;形成一种团队文化;最终是为项目服务的,我们所做的一切都是为了优化项目和流程,提高我们的工作效率。
1.3 备注
本规范文档一经确认,前端人员必须按文档规范进行前端页面开发。本文档如有不对或者不合格的地方请及时提出,经讨论后决定可以修改此文档。
二、 文档规范
2.1 基本准则
符合web2.0标准,语义化html,结构、表现、行为三层分离,兼容性优良,页面性能方便,代码简洁明了有序,尽可能的减少服务器负载,保证最快的解析速度。
2.2 文件规范
- 以项目名称建立文件夹,以日期建立文件夹区别版本,最终版本须有以下几个文件夹:html、psd、jpg、需求资料。html文件夹里有css、js、images、swf(有flash文件的情况)。另:如果项目较多,需要给每个项目名称前上首个拼音的大写字母,例如K-宽系列。
- html文件命名:英文命名,后缀为.html,同时同目录需创建“必读.txt”文件,里面须有二级目录和对应的html文件,以及提醒开发人员需要注意的地方,以方便开发人员添加功能时查找对应页面。
- css文件命名:英文命名,后缀为.css,小型网站只需一个文件style.css,门户类型网站需按公用部门和私有部门以功能模块来命名。
- js文件命名:英文命名,后缀为.js,公用common.js,其他按实际模块需求命名。
2.3 html书写规范
- 文档类型声明及编码:统一为html5声明类型<!doctype html>;编码统一为<meta charset="utf-8">;书写时用IDE实现层次分明的缩进。
- 非特殊情况下样式文件必须外链至<head>…</head>之间;非特殊情况下JavaScript文件必须外链至页面底部。
- 引用样式文件或JavaScript文件时,须略掉默认类型声明,写法如下:
<link rel="stylesheet" href="…" />
<style>…</style>
<script src="…"></script>。
- 引用js库文件,文件须包含库名称及版本号,以及是否为压缩版,比如jquery.1.41.min.js;引用插件,文件名为库名+插件名称,比如jquery.cookie.js。
- 所有编码均遵循xhtml标准,标签、属性、属性命名必须由小写字母及减号数字组成,且所有标签必须闭合,包括br(<br />),hr(<hr />)等;属性值必须用双引号包括。
- 充分利用无兼容性问题的html自身标签,比如span、em、strong、optgroup、label等;需要为html元素添加自定义属性的时候, 首先要考虑下有没有默认的已有的合适标签去设置,如果没有,可以使用须以"data-"为前缀来添加自定义属性,避免使用"data:"等其他命名方式。
- 语义化html,如:标题根据重要性用h*(同一页面只能有一个h1),段落标记用p,列表用ul,内联元素中不可嵌套块级元素。
- 尽可能减少div嵌套, 如:
<div class=”box”> <div class=”welcome”>欢迎XXX,您的用户名是 <div class=”name”>用户名</div> </div> </div> |
完全可以用以下代码替代:
<div class=”box”> <p>欢迎XXX,您的用户名是<span>用户名</span></p> </div> |
- 书写链接是,必须避免重定向,例如:href=“http://gtadata.com/”,即需在URL地址后面加上“/”;
- 在页面中尽量避免使用style属性,即style="…"。
- 必须为含有描述性表单元素(input, textarea) 添加labe,如:
<p>姓名:<input type=”text” id=”name” name=”name” /></p> |
须写成:
<p> <label for=”name”>姓名:</label> <input type=”text” id=”name” /> </p> |
- 能以背景形式呈现的图片,尽量写入css样式中。
- 重要图片必须加上alt属性,给重要的元素和截断的元素加上title。
- 给区块代码及重要功能(比如循环)加上注释,方便后台添加功能。
- 特殊符号使用:尽可能使用代码替代:比如 <(<)& >(>)& 空格( )& »(»)等等。
- class & id 参见 css书写规范。
2.4 css书写规范
- 编码统一为utf-8。
- 开发建议采用分层的设计思想,主要为三个大的层次:全局样式、通用元素和结构布局、具体的块状表现区域。前端固定结构内可进一步细分到:导航系统(包括:菜单、导航、面包屑、站点地图),辅助系统(提示、指南、FAQ),全局通用性功能模块(搜索功能块、登入/登出功能块)。可参考我个人的css架构文档。
- class与id的使用:id是唯一的并是父级的,class是可以重复的并是子级的,所以id仅使用在大的模块上,class可用在重复使用率高及子级中;id原则上尽量不用,为JavaScript预留钩子的除外。
- 为JavaScript预留钩子的命名, 请以 js- 起始,比如: js-hide,js-show。
- class与id命名:样式名称由 小写英文 & 数字 & - 来组合命名,如main、block-title、btn01;避免使用中文拼音, 尽量使用简易的单词组合;总之,命名要语义化,简明化。
- 规避class与id命名(这一点很重要):
a) 通过从属写法规避,示例见e;
b) 取父级元素id/class命名部分命名, 示例见e;
c) 驼峰式命名,程序员常用,示例见e;
d) 重复使用率高的命名,请以自己代号加减号起始,比如dp-clear;
e) a、b、c三条,适用于在2中已建好框架的页面,如:
要在2中已建好框架的页面代码<div class="main"></div>中加入新的div元素,
n 按a命名法则:
<div class=”main”><div class=”title”>…</div></div> |
样式写法:.main .title{…}
n 按b命名法则:
<div class=”main”><div class=”main-title”>…</div></div> |
样式写法:.main-title{…}
n 按c命名法则:
<div class=”main”><div class=”mainTitle”>…</div></div> |
样式写法:.mainTitle{…}
- css属性书写顺序, 建议遵循 布局定位属性-->自身属性-->文本属性-->其他属性. 此条可根据自身习惯书写,但尽量保证同类属性写在一起。属性列举:
n 布局定位属性主要包括: float、clear、position、top、right、bottom、left、display、visibility、overflow等;
n 自身属性主要包括:width、height、margin、padding、background、border;
n 文本属性主要包括:font、color、text-align、vertical-align、text-decoration、text-indent、white-space等;
n 其他属性包括:list-style、cursor、 z-index、zoom等。
我所列出的这些属性只是最常用到的,并不代表全部。
- 书写代码前,考虑并提高样式重复使用率。
- 充分利用html自身属性及样式继承原理减少代码量,比如:
<ul class=”list”><li>这是标题列表<span>2012-10-11</span></li></ul> |
定义
ul.list li{position:relative}
ul.list li span{position:absolute; right:0}
即可实现日期居右显示
- 样式表中中文字体名, 请务必转码成unicode码, 以避免编码错误时乱码,常用中文如下:
中文名 |
英文名 |
Unicode |
Unicode 2 |
Mac OS |
|||
华文黑体 |
STHeiti |
\534E\6587\9ED1\4F53 |
华文黑体 |
华文楷体 |
STKaiti |
\534E\6587\6977\4F53 |
华文楷体 |
华文宋体 |
STSong |
\534E\6587\5B8B\4F53 |
华文宋体 |
华文仿宋 |
STFangsong |
\534E\6587\4EFF\5B8B |
华文仿宋 |
Windows |
|||
黑体 |
SimHei |
\9ED1\4F53 |
黑体 |
宋体 |
SimSun |
\5B8B\4F53 |
宋体 |
新宋体 |
NSimSun |
\65B0\5B8B\4F53 |
新宋体 |
仿宋 |
FangSong |
\4EFF\5B8B |
仿宋 |
楷体 |
KaiTi |
\6977\4F53 |
楷体 |
微软雅黑 |
Microsoft YaHei |
\5FAE\8F6F\96C5\9ED1 |
微软雅黑 |
Office |
|||
隶书 |
LiSu |
\96B6\4E66 |
隶书 |
幼圆 |
YouYuan |
\5E7C\5706 |
幼圆 |
- 背景图片请尽可能使用sprite技术,减小http请求,考虑到多人协作开发,sprite按模块制作。
- 使用table标签时(尽量避免使用table标签),请不要用width、height、cellspacing、cellpadding等table属性直接定义表现,应尽可能的利用table自身私有属性分离结构与表现,如:
thead、tr、th、td、tbody、foot、colgroup、scope;
而cellspaing及cellpadding的css控制方法如下:
table{border:0; margin:0; border-collapse:collapse;}
table th, table td{padding:0;}
- 杜绝使用<meta http-equiv="X-UA-Compatible" content="IE=7" /> 兼容ie8,和代码*html写法。
- 用png图片做图片时,要求图片格式为png-8格式,若png-8实在影响图片质量或其中有半透明效果,请为ie6单独定义背景:
background:none;
_filter:progid:DXImageTransform.Microsoft.AlphaImageLoader(sizingMethod=crop, src=’img/bg.png’);
如果用到的半透明png图片很多,可引用我提供的png.js和使用方法兼容ie6。
- 兼容性属性的使用,比如text-shadow等css3的相关属性在保证目前主流浏览器使用情况下可以使用来对页面进行锦上添花式的设计。
- 减少使用影响性能的属性,比如position:absolute、float 。
- 必须为大区块样式添加注释,小区块适量注释。
- 代码缩进与格式:建议单行书写,可根据自身习惯,后期优化统一处理。
2.5 JavaScript书写规范
- 文件编码统一为utf-8,书写过程过,每行代码结束必须有分号;原则上所有功能均根据XXX项目需求原生开发,以避免网上down下来的代码造成的代码污染(沉冗代码、与现有代码冲突、... )。
- 库引入:原则上仅引入jQuery库,若需引入第三方库,须与团队其他人员讨论决定。
- 变量命名: 驼峰式命名。原生JavaScript变量要求是纯英文字母, 首字母须小写,如liItem;另,要求变量集中声明,避免全局变量。
- 类命名:首字母大写, 驼峰式命名,如LiItem。
- 函数命名:首字母小写驼峰式命名,如liItem()。
- 命名语义化,尽可能利用英文单词或其缩写。
- 尽量避免使用存在兼容性及消耗资源的方法或属性,比如eval() 、innerText等。
- 后期优化中,JavaScript非注释类中文字符须转换成unicode编码使用,以避免编码错误时乱码显示。
- 代码结构明了,加适量注释,提高函数重用率。
- 注重与html分离,减小reflow,注重性能。
2.6 图片规范
- 所有页面元素类图片均放入img文件夹,测试用图片放于img/demoimg文件夹。
- 图片格式仅限于gif、png、jpg。
- 命名全部用小写英文字母、数字、减号的组合,其中不得包含汉字、空格、特殊字符;尽量用易懂的词汇,便于团队其他成员理解;另,命名分头尾两部分,用减号隔开,比如ad-left01.gif、btn-submit.gif。
- 在保证视觉效果的情况下选择最小的图片格式与图片质量,以减少加载时间。
- 尽量避免使用半透明的png图片(若使用,请参考css规范相关说明)。
- 运用css sprite技术集中小的背景图或图标,减小页面http请求,但注意,请务必在对应的sprite.psd源图中划参考线,并保存至psd目录下。
2.7 注释规范
- html注释:注释格式 <!--这儿是注释-->,'--'只能在注释的始末位置,不可置入注释文字区域。
- css注释:注释格式 /*这儿是注释*/;
- JavaScript注释:单行注释使用 //这儿是单行注释,多行注释使用 /* 这儿有多行注释 */。
三、 开发及测试工具约定
建议使用Aptana、Dw、Vim,亦可根据自己喜好选择,但须遵循如下原则:
- 不可利用IDE的视图模式‘画’代码。
- 不可利用IDE生成相关功能代码,比如Dw内置的一些功能js。
- 编码必须格式化,比如缩进。
- 前期开发仅测试FireFox、IE6、IE7、IE8、IE9,后期优化时加入Opera、Chrome。
- 建议测试顺序: FireFox-->IE7-->IE8--> IE9-->IE6-->Opera-->Chrome, 建议安装firebug及IE Tab Plus插件,安装调试利器IETester和debugBar插件。
四、 CSS Hack
即使是完美的CSS也未必能在目前众多的浏览器中呈现一致的效果,所以,CSS Hack在很多情况下都是必要的,建议先对css标准支持得比较好的浏览器(Firefox或者Chrome)为主编辑css,最后在处理ie的兼容性。有一个方法——单独为IE建立一个css文件(比如:for-ie.css或者ie-hack.css等),最后在html文件中,通过ie的条件注释按需引入。这个方法不推荐使用,不利于后期维护,假如后期是别人来修改你的css,可能他只用firebug来调试,修改后却发现IE始终不兼容,找了半天才想到还有个ie-hack.css。
五、 其他规范
- 开发过程中严格按分工完成页面,以提高css复用率,避免重复开发。
- 减小沉冗代码,书写所有人都可以看的懂的代码,简洁易懂是一种美德,为用户着想,为服务器着想。