前端开发规范:命名规范、html规范、css规范

787 阅读10分钟

命名规范

由历史原因及个人习惯引起的 DOM 结构、命名不统一,导致不同成员在维护同一页面时,效率低下,迭代、维护成本极高。

项目命名

全部采用小写方式, 以下划线分隔。 例:my_project_name

目录命名

有复数结构时,要采用复数命名法。

  • 项目文件夹:例: projectname
  • 样式文件夹:例: styles
  • 脚本文件夹:例: utils
  • 样式类图片文件夹:例: imgs

图片命名

命名顺序

图片命名建议以以下顺序命名:

图片业务(可选) +(mod_)图片功能类别(必选)+ 图片模块名称(可选) + 图片精度(可选)

  • 图片业务:

    • pp_:拍拍
    • wx_:微信
    • sq_:手Q
    • jd_:京东商城
  • 图片功能类别:

    • mod_:是否公共,可选
    • icon:模块类固化的图标
    • logo:LOGO类
    • spr:单页面各种元素合并集合
    • btn:按钮
    • bg:可平铺或者大背景
  • 图片模块名称:

    • goodslist:商品列表
    • goodsinfo:商品信息
    • userava tar:用户头像
  • 图片精度:

    • 普清:@1x
    • Retina:@2x | @3x
    • … 例:
公共模块:
wx_mod_btn_goodlist@2x.png
wx_mod_btn_goodlist.png
mod_btn_goodlist.png 

非公共模块:
wx_btn_goodlist@2x.png
wx_btn_goodlist.png
btn_goodlist.png

交叉业务协作

业务交叉协作的时候,为了避免图片命名冲突,建议图片名加上业务和模块前辍,如拍拍侧和手Q侧的业务交叉合作时,侧栏导航icon雪碧图命名:

推荐:
pp_icon_mod_sidenav.png

不推荐:
icon_mod_sidenav.png

处理高清图片的时候,命名应该加上图片相应的精度说明

推荐:
jdc_logo@1x.png
jdc_logo@2x.png

不推荐:
jdc_logo.png
jdc_logo_retina.png

文件命名

确保文件命名总是以字母开头而不是数字,且字母一律小写,以下划线连接且不带其他标点符号,如:

<!-- HTML -->
jdc.html
jdc_list.html
jdc_detail.html

<!-- SASS -->
jdc.scss
jdc_list.scss
jdc_detail.scss

HTML 规范

元素及标签闭合

HTML元素共有以下5种:

  • 空元素:area、base、br、col、command、embed、hr、img、input、keygen、link、meta、param、source、track、wbr
  • 原始文本元素:script、style
  • RCDATA元素:textarea、title
  • 外来元素:来自MathML命名空间和SVG命名空间的元素。
  • 常规元素:其他HTML允许的元素都称为常规元素。 元素标签的闭合应遵循以下原则:
  • 原始文本元素、RCDATA元素以及常规元素都有一个开始标签来表示开始,一个结束标签来表示结束。
  • 某些元素的开始和结束标签是可以省略的,如果规定标签不能被省略,那么就绝对不能省略它。
  • 空元素只有一个开始标签,且不能为空元素设置结束标签。
  • 外来元素可以有一个开始标签和配对的结束标签,或者只有一个自闭合的开始标签,且后者情况下该元素不能有结束标签。 HTML代码大小写 HTML标签名、类名、标签属性和大部分属性值统一用小写

书写风格

HTML代码大小写

推荐:

<div class="demo"></div>

不推荐:

<div class="DEMO"></div>
<DIV CLASS="DEMO"></DIV>

HTML文本、CDATA、JavaScript、meta标签某些属性等内容可大小写混合

<!-- 优先使用 IE 最新版本和 Chrome Frame -->
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>

<!-- HTML文本内容 -->
<h1>I AM WHAT I AM </h1>

<!-- JavaScript 内容 -->
<script type="text/javascript">
	var demoName = 'demoName';
	...
</script>
	
<!-- CDATA 内容 -->
<script type="text/javascript"><![CDATA[
...
]]></script>

类型属性

不需要为 CSS、JS 指定类型属性,HTML5 中默认已包含

推荐:

<link rel="stylesheet" href="" >
<script src=""></script>

不推荐:

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

元素属性

元素属性值使用双引号语法。属性应当按照以下给出的顺序依次排列,确保代码的易读性。

  1. class
  2. id, name
  3. data-*
  4. src, for, type, href, value
  5. title, alt
  6. role, aria-*
<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

布尔型属性可以在声明时不赋值:

<input type="text" disabled>

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

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

特殊字符引用

文本可以和字符引用混合出现。这种方法可以用来转义在文本中不能合法出现的字符。 在 HTML 中不能使用小于号 “<” 和大于号 “>”特殊字符,浏览器会将它们作为标签解析,若要正确显示,在 HTML 源代码中使用字符实体

推荐:

<a href="#">more&gt;&gt;</a>

不推荐:

<a href="#">more>></a>

代码缩进

统一使用四个空格进行代码缩进,使得各编辑器表现一致(各编辑器有相关配置)

<div class="jdc">
    <a href="#"></a>
</div>

纯数字输入框

使用 type="tel" 而不是 type="number"

<input type="tel">

代码嵌套

元素嵌套规范,每个块状元素独立一行,内联元素可选

推荐:

<div>
    <h1></h1>
    <p></p>
</div>	
<p><span></span><span></span></p>

不推荐:

<div>
    <h1></h1><p></p>
</div>	
<p> 
    <span></span>
    <span></span>
</p>

段落元素与标题元素只能嵌套内联元素

推荐:

<h1><span></span></h1>
<p><span></span><span></span></p>

不推荐:

<h1><div></div></h1>
<p><div></div><div></div></p>

常用的标签

标签语义嵌套常见错误常用属性(加粗的为不可缺少的或建议的)
<a></a>超链接/锚a不可嵌套ahref,name,title,rel,target
<br />换行
<button></button>按钮不可嵌套表单元素type,disabled
<dd></dd>定义列表中的定义(描述内容)只能以dl为父容器,对应一个dt
<del></del>文本删除
<div></div>块级容器
<dl></dl>定义列表只能嵌套dt和dd
<dt></dt>定义列表中的定义术语只能以dl为父容器,对应多个dd
<em></em>强调文本
<form></form>表单action,target,method,name
<h1></h1>标题从h1到h6,不可嵌套块级元素
<iframe></iframe>内嵌一个网页frameborder,width,height,src,scrolling,name
<img />图像alt,src,width,height
<input />各种表单控件type,name,value,checked,disabled,maxlength,readonly,accesskey
<label></label>标签为input元素定义标注for
<li></li>列表项只能以ul或ol为父容器
<link />引用样式或icon不可嵌套任何元素type,rel,href
<meta />文档信息只用于head content,http-equiv,name
<ol></ol>有序列表只能嵌套li
<option></option>select中的一个选项仅用于selectvalue,selected,disabled
<p></p>段落不能嵌套块级元素
<script></script>引用脚本不可嵌套任何元素type,src
<select></select>列表框或下拉框只能嵌套option或optgroupname,disabled,multiple
<span></span>内联容器
<strong></strong>强调文本
<style></style>引用样式不可嵌套任何元素type,media
<sub></sub>下标
<sup></sup>上标
<table></table>表格只可嵌套表格元素width,align,background,cellpadding,cellspacing,summary,border
<tbody></tbody>表格主体只用于table
<td></td>表格中的单元格只用于trcolspan,rowspan
<textarea></textarea>多行文本输入控件name,accesskey,disabled,readonly,rows,cols
<tfoot></tfoot>表格表尾只用于table
<th></th>表格中的标题单元格只用于trcolspan,rowspan
<thead></thead>表格表头只用于table
<title></title>文档标题只用于head
<tr></tr>表格行嵌套于table或thead、tbody、tfoot
<ul></ul>无序列表只能嵌套li

HTML标准模板

<!DOCTYPE html>
<html lang="zh-CN">
    <head>
        <meta charset="UTF-8">
        <title>HTML5标准模版</title>
    </head>
    <body>	
    </body>
</html>

移动端viewport

若页面欲对移动设备友好,需指定页面的 viewport。可参考淘宝移动端

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

注释规范

单行注释

一般用于简单的描述,如某些状态描述、属性描述等

注释内容前后各一个空格字符,注释位于要注释代码的上面,单独占一行

推荐:

<!-- Comment Text -->
<div>...</div>

不推荐:

<div>...</div><!-- Comment Text -->	
	
<div><!-- Comment Text -->
    ...
</div>

模块注释

一般用于描述模块的名称以及模块开始与结束的位置

注释内容前后各一个空格字符, 表示模块开始, 表示模块结束,模块与模块之间相隔一行

推荐写法:

<!-- S Comment Text A -->	
<div class="mod_a">
    ...
</div>
<!-- E Comment Text A -->
	
<!-- S Comment Text B -->	
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

不推荐写法:

<!-- S Comment Text A -->
<div class="mod_a">
    ...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->	
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

嵌套模块注释

当模块注释内再出现模块注释的时候,为了突出主要模块,嵌套模块不再使用

<!-- S Comment Text -->
<!-- E Comment Text -->

而改用

<!-- /Comment Text -->

注释写在模块结尾标签底部,单独一行。

<!-- S Comment Text A -->
<div class="mod_a">
		
    <div class="mod_b">
        ...
    </div>
    <!-- /mod_b -->
    	
    <div class="mod_c">
    	...
    </div>
    <!-- /mod_c -->
		
</div>
<!-- E Comment Text A -->

CSS规范

代码风格

代码格式化

样式书写一般有两种:一种是紧凑格式 (Compact)

.jdc{ display: block;width: 50px;}
一种是展开格式(Expanded)

.jdc{
    display: block;
    width: 50px;
}

统一使用展开格式书写样式

代码大小写

样式选择器,属性名,属性值关键字全部使用小写字母书写,属性字符串允许使用大小写。

/* 推荐 */
.jdc{
	display:block;
}
	
/* 不推荐 */
.JDC{
	DISPLAY:BLOCK;
}

选择器

尽量少用通用选择器 * 不使用 ID 选择器 不使用无具体语义定义的标签选择器

/* 推荐 */
.jdc {}
.jdc li {}
.jdc li p{}

/* 不推荐 */
*{}
#jdc {}
.jdc div{}

代码缩进

统一使用四个空格进行代码缩进,使得各编辑器表现一致(各编辑器有相关配置)

.jdc {
    width: 100%;
    height: 100%;
}

分号

每个属性声明末尾都要加分号;

.jdc {
    width: 100%;
    height: 100%;
}

代码易读性

左括号与类名之间一个空格,冒号与属性值之间一个空格

/* 推荐 */
.jdc { 
    width: 100%; 
}

/* 不推荐 */
.jdc{ 
    width:100%;
}

逗号分隔的取值,逗号之后一个空格

/* 推荐 */
.jdc {
    box-shadow: 1px 1px 1px #333, 2px 2px 2px #ccc;
}

/* 不推荐 */
.jdc {
    box-shadow: 1px 1px 1px #333,2px 2px 2px #ccc;
}

为单个css选择器或新申明开启新行

/* 推荐 */
.jdc, 
.jdc_logo, 
.jdc_hd {
    color: #ff0;
}
.nav{
    color: #fff;
}

/* 不推荐 */
.jdc,jdc_logo,.jdc_hd {
    color: #ff0;
}.nav{
    color: #fff;
}

颜色值 rgb() rgba() hsl() hsla() rect() 中不需有空格,且取值不要带有不必要的 0

/* 推荐 */
.jdc {
    color: rgba(255,255,255,.5);
}

/* 不推荐 */
.jdc {
    color: rgba( 255, 255, 255, 0.5);
}

属性值十六进制数值能用简写的尽量用简写

/* 推荐 */
.jdc {
    color: #fff;
}

/* 不推荐 */
.jdc {
    color: #ffffff;
}

不要为 0 指明单位

/* 推荐 */
.jdc {
    margin: 0 10px;
}

/* 不推荐 */
.jdc {
    margin: 0px 10px;
}

属性值引号 css属性值需要用到引号时,统一使用单引号

/* 推荐 */
.jdc { 
	font-family: 'Hiragino Sans GB';
}

/* 不推荐 */
.jdc { 
	font-family: "Hiragino Sans GB";
}

属性书写顺序

建议遵循以下顺序:

布局定位属性:display / position / float / clear / visibility / overflow 自身属性:width / height / margin / padding / border / background 文本属性:color / font / text-decoration / text-align / vertical-align / white- space / break-word 其他属性(CSS3):content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient …

.jdc {
    display: block;
    position: relative;
    float: left;
    width: 100px;
    height: 100px;
    margin: 0 10px;
    padding: 20px 0;
    font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif;
    color: #333;
    background: rgba(0,0,0,.5);
    -webkit-border-radius: 10px;
    -moz-border-radius: 10px;
    -o-border-radius: 10px;
    -ms-border-radius: 10px;
    border-radius: 10px;
}

mozilla官方属性顺序推荐

CSS3浏览器私有前缀写法

CSS3 浏览器私有前缀在前,标准前缀在后

.jdc {
    -webkit-border-radius: 10px;
    -moz-border-radius: 10px;
    -o-border-radius: 10px;
    -ms-border-radius: 10px;
    border-radius: 10px;
}

注释规范

  • 注释以字符 /* 开始,以字符*/ 结束
  • 注释不能嵌套
/*Comment Text*/

单行注释

注释内容第一个字符和最后一个字符都是一个空格字符,单独占一行,行与行之间相隔一行

推荐:

/* Comment Text */
.jdc{}

/* Comment Text */
.jdc{}

不推荐:

/*Comment Text*/
.jdc{
	display: block;
}
.jdc{
	display: block;/*Comment Text*/
}

模块注释

注释内容第一个字符和最后一个字符都是一个空格字符,/* 与 模块信息描述占一行,多个横线分隔符-与*/占一行,行与行之间相隔两行

推荐:

/* Module A
---------------------------------------------------------------- */
.mod_a {}

/* Module B
---------------------------------------------------------------- */
.mod_b {}
不推荐:

/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}

文件信息注释

在样式文件编码声明 @charset 语句下面注明页面名称、作者、创建日期等信息

@charset "UTF-8";
/**
 * @desc File Info
 * @author Author Name
 * @date 2015-10-10
 */

重置样式

移动端

* { -webkit-tap-highlight-color: transparent; outline: 0; margin: 0; padding: 0; vertical-align: baseline; }
body, h1, h2, h3, h4, h5, h6, hr, p, blockquote, dl, dt, dd, ul, ol, li, pre, form, fieldset, legend, button, input, textarea, th, td { margin: 0; padding: 0; vertical-align: baseline; }
img { border: 0 none; vertical-align: top; }
i, em { font-style: normal; }
ol, ul { list-style: none; }
input, select, button, h1, h2, h3, h4, h5, h6 { font-size: 100%; font-family: inherit; }
table { border-collapse: collapse; border-spacing: 0; }
a { text-decoration: none; color: #666; }
body { margin: 0 auto; min-width: 320px; max-width: 640px; height: 100%; font-size: 14px; font-family: -apple-system,Helvetica,sans-serif; line-height: 1.5; color: #666; -webkit-text-size-adjust: 100% !important; text-size-adjust: 100% !important; }
input[type="text"], textarea { -webkit-appearance: none; -moz-appearance: none; appearance: none; }

PC端

html, body, div, h1, h2, h3, h4, h5, h6, p, dl, dt, dd, ol, ul, li, fieldset, form, label, input, legend, table, caption, tbody, tfoot, thead, tr, th, td, textarea, article, aside, audio, canvas, figure, footer, header, mark, menu, nav, section, time, video { margin: 0; padding: 0; }
h1, h2, h3, h4, h5, h6 { font-size: 100%; font-weight: normal }
article, aside, dialog, figure, footer, header, hgroup, nav, section, blockquote { display: block; }
ul, ol { list-style: none; }
img { border: 0 none; vertical-align: top; }
blockquote, q { quotes: none; }
blockquote:before, blockquote:after, q:before, q:after { content: none; }
table { border-collapse: collapse; border-spacing: 0; }
strong, em, i { font-style: normal; font-weight: normal; }
ins { text-decoration: underline; }
del { text-decoration: line-through; }
mark { background: none; }
input::-ms-clear { display: none !important; }
body { font: 12px/1.5 \5FAE\8F6F\96C5\9ED1, \5B8B\4F53, "Hiragino Sans GB", STHeiti, "WenQuanYi Micro Hei", "Droid Sans Fallback", SimSun, sans-serif; background: #fff; }
a { text-decoration: none; color: #333; }
a:hover { text-decoration: underline; }

SASS规范

参见SASS规范|Autu.io - 前端代码规范

媒体查询

参见媒体查询|Autu.io - 前端代码规范

移动端常见私有属性

参见移动端常用私有属性|Autu.io - 前端代码规范

JS规范、VUE规范

详见后续

参考文档