web前端规范

icecity1306 2014-11-08

展开全文

通用规范

tab键用两个空格代替
　　因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四个空格的位置，而在linux下会变成占八个空格的位置（除非你自己设定了tab键所占的位置长度）。
每个样式属性或者每句代码后加 ";"
方便压缩工具"断句"。

CSS 规范

文件和目录命名约定

一律小写，必须是英文单词或者汉语拼音，以英语单词优先，多个单词以连字符 ( - ) 连接。 只能出现小写引文字母，数字和连字符。
很多浏览器会将含有这些词的作为广告拦截： ad、ads、adv、banner、sponsor、gg、guangg、guanggao等页面中尽量避免采用以上词汇来命名。
该命令规范适用于所有前端维护的内容和相关目录。(html, css, js, png, gif, jpg, ico)。

空格规范

用两个空格来代替制表符（tab） —— 这是唯一能保证在所有环境下获得一致展现的方法；
嵌套元素应当缩进一次 —— 即两个空格；
对于属性的定义，确保全部使用双引号，绝不要使用单引号；
不要省略可选的结束标签，如：</li>,</body>；
习惯性书写注释，方便日后维护；

文件编码约定

所有文件统一采用UTF-8无BOM编码。换行格式为 unix 格式。

id和class命名约定

id 和 class 的命名基本原则: 内容优先，表现为辅。首先根据内容来命名，如:#header,#footer,.main-nav.如根据内容无法找到合适的命名，可以再结合表现进行命名，如：col-main, col-sub, col-extra,blue-box
id 和 class 的名称一律小写，多个单词以连字符连接，如： main-wrap
id 和 class 的名称只能出现，小写字母，数字和连字符( - )(js钩子除外)
id 和 class 的名称尽量使用英文单词命名,如确实找不到合适的单词，可以使用拼音，如：zhidao-com
在不影响语意的情况下，id 和 class 的名称可以适当使用缩写，如: col, nav, hd, bd, fd( 缩写只用来表示结构，不允许写任何样式)。不要自造缩写。
class 对于选中命名.selected;对于hover，支持伪类使用:hover，不支持的使用 .hover，隐藏使用.hide 。
id 和 class 的选择，如果只使用一次，使用id,如果使用多次使用.class，如果需要和js交互，使用id,如果需要交互并且页面中有大量重复，请参见下一条。
对于作为js钩子的 id 和 class 命名规则为以”J_“开头(J,象形钩子的形状)，后面加上原应有的命名，在使用class的时候需要放在最前面。如:class="J_tab-content some-mod-content"。（注意：钩子，不允许在css中定义任何的样式效果）
很多浏览器会将含有这些词的作为广告拦截： ad、ads、adv、banner、sponsor、gg、guangg、guanggao等页面中尽量避免采用以上词汇来命名。

文件引用

页面中不允许出现css内容(包括行内样式和style)
每个页面中至多包括3个css文件，1个产品级 1个模块级 1个页面级别

选择器

命名比较短的词，或者缩写的不允许直接定义样式，如：.title,.hd,.bd,.body.必须用上级节点进行限定,如：.recommend-mod .title

通用结构

页面中的块采用如下结构

<div class="mod recommend-mod">
 <div class="hd recommend-title">Tilte </div>
 <div class="bd recommend-body">contents</div>
 <div class="ft recommend-footer">footer </div>
</div>

没有内容的部分可以省略，其中用来表示结构的 mod hd bd ft 不允许直接定义样式（避免嵌套带来样式问题）,需要定义样式的时候需要另外增加class以控制样式如：

<div class="mod recommend-mod">
  <div class="hd recommend-title">Tilte </div>
  <div class="bd recommend-body">contents</div>
  <div class="ft recommend-footer">footer </div>
</div>

当2个以上的结构不存在的时候可以不是采用此结构，如，没有hd和ft,bd也可以省略

多选择器规则之间换行

当样式针对多个选择器时每个选择器占一行

/ 推荐的写法 /
a.btn,
input.btn,
input[type="button"] {
......
}

z-index

自己写的z-index的值不能超过 100 (通用组的除外)
页面中的元素内容的z-index不能超过10(popup poptip除外)，需要按照内容定义1 2 3 4不允许直接使用如1000，9999
popup poptip的z-index需要按照内容使用 99以下，10以上的值（11,12,13，也可以小于10），不允许直接使用1000，9999之类大值

现在通用z-index记录,使用时请避开和灵活使用

z-index	使用者	类型
<10	page-content	页面级别
>10, <99	page-popup	页面级别
20	usercard用户名片	common通用
	MSG气泡消息	common通用
	Dialog-Cover	common通用
	Dialog	common通用

css属性顺序

显示属性；
元素位置；
元素属性；
元素内容属性；

css书写顺序：

例子:
.header {
 /* 显示属性 */
 display || visibility
 list-style
 position
 top || right || bottom || left
 z-index
 clear
 float

 /* 自身属性 */
 width
 max-width || min-width
 height
 max-height || min-height
 overflow || clip
 margin 
 padding
 outline
 border
 background

 /* 文本属性 */
 color
 font
 text-overflow
 text-align
 text-indent
 line-height
 white-space
 vertical-align
 cursor
 content
}

css规范

小图片（必须）sprite 合并
每个样式属性后加 ";"
禁止将样式写为单行

如
.hotel-content {margin: 10px; background-color: #efefef;}
单行显示不好注释，不好备注，这应该是压缩工具的活儿~
禁止使用行内（inline）样式
禁止使用"*"来选择元素

/*别这样写*/
* {
margin: 0;
padding: 0;
}

这样写是没有必要的，一些元素在浏览器中默认有margin或padding值，但是只是部分元素，没有必要将所有元素的margin、padding值都置为0。

前端规范之JavaScript

命名规范

文件命名可读性强
文件夹、文件的命名与命名空间应能代表代码功能，可读性强。
命名空间建议以“产品线缩写+子项目+功能接口”的方式命名

:::javascript
ik.item.detailAPI           // 命名空间 =》 知道+物品+详细功能接口

函数命名
驼峰命名方式

:::javascript
function funName() {}

常量

大写

:::javascript
var VARIABLENAME

变量

驼峰命名

:::javascript
var variableName

编码规则

排版缩进

采用统一的缩进方式排版代码。缩进为4个ASCII空格

:::javascript
If(condition1 || condition2) {
  action1;
} else if (condition3 && condition4) {
  action2;
} else if (condition5
          && condition6
          && condition7
          && condition8) {
  action2;
} else {
  default action;
}

关键词、条件括弧后面使用空格；运算操作符号两侧使用空格；语句分割符‘,’后面使用空格

:::javascript
var name[空格]=[空格]value;
if[空格](a,[空格]b) {
}

左大括号"{"可以居行尾，也可写在下行首（独自一行）；右大括号"}"单独占一行，居行首

:::javascript
if (a && b) {
    }
------------------------
if (a && b) 
{
}

句末必须用分号结尾

:::javascript
var fn = function () {
};//这里没有分号的话，脚本解析器会报错！！！
(function () {
        alert(1);
})();

单行过长应在适当位置予以换行,增强可读性

if 语句括号中的条件若过多过长，应予以折行；折行后，||、&& 等符号应与 “(” 后的第一个字母纵向对齐

:::javascript
if (condition1 
    && condition2 
    || condition3) {
}

if、while、for、do语句的执行体总是用"{"和"}"括起来，即使在其结构体内只有一条语句

:::javascript
if (s==100) {
    alert('shit!');
}

语法意义相互独立的代码将用空行分隔

:::javascript
a++; b++;   //！！！避免同一行书写两个表达式
if (a > b) {
    value = a;  //行间不用空行间隔
}

var variableName = value;   //与上一代码行使用空行间隔

注释规范

文件注释

文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录

函数描述

文件版本、创建或者修改时间、功能、作者

:::javascript
/**
* @file Image.js
* @description 功能详细描述
*/

函数或者类等都要添加头描述

:::javascript
/**
* 简述
*
* 功能详细描述
*
* @param <String> arg1 参数1
* @param <Number> arg2 参数2，默认为0
* @return <Boolean> 看xxx是否成功
*/
function fooFunction (arg1, arg2) {
}

操作注释

单行注释,写在代码上面

多行注释

:::javascript
/*
* 注释操作说明
*/
for( var i = 0; i < obj.lenght; i++) {
}

注释标签参考

标签	描述
@addon	把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中。
@argument	用大括号中的自变量类型描述一个自变量。
@author	函数/类作者的姓名。
@base	如果类是继承得来，定义提供的类名称。
@class	用来给一个类提供描述，不能用于构造器的文档中。
@constructor	描述一个类的构造器。
@deprecated	表示函数/类已被忽略。
@exception	描述函数/类产生的一个错误。
@exec
@extends	表示派生出当前类的另一个类。
@fileoverview	表示文档块将用于描述当前文件。这个标签应该放在其它任何标签之前。
@final	指出函数/类。
@ignore	让jsdoc忽视随后的代码。
@link	类似于@link标签，用于连接许多其它页面。
@member	定义随后的函数为提供的类名称的一个成员。
@param	用大括号中的参数类型描述一个参数。
@private	表示函数/类为私有，不应包含在生成的文档中。
@requires	表示需要另一个函数/类。
@return	描述一个函数的返回值。
@returns	描述一个函数的返回值。
@see	连接到另一个函数/类。
@throws	描述函数/类可能产生的错误。
@type	指定函数/成员的返回类型。
@version	函数/类的版本号。