代码规范
DOCTYPE 声明(视具体情况而定,一般采用HTML5的声明)
HTML文件必须加上 DOCTYPE 声明,并统一使用 HTML5 的文档声明:
<!DOCTYPE html>
页面语言LANG
推荐使用属性值 cmn-Hans-CN(简体, 中国大陆),但是考虑浏览器和操作系统的兼容性,目前仍然使用 zh-CN 属性值
<html lang="zh-CN">
其他地区语言参考:
zh-SG 中文 (简体, 新加坡) 对应 cmn-Hans-SG 普通话 (简体, 新加坡)
zh-HK 中文 (繁体, 香港) 对应 cmn-Hant-HK 普通话 (繁体, 香港)
zh-MO 中文 (繁体, 澳门) 对应 cmn-Hant-MO 普通话 (繁体, 澳门)
zh-TW 中文 (繁体, 台湾) 对应 cmn-Hant-TW 普通话 (繁体, 台湾)
CHARSET
一般情况下统一使用 “UTF-8” 编码
<meta charset="UTF-8">
由于历史原因,有些业务可能会使用 “GBK” 编码
<meta charset="GBK">
元素及标签闭合
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元素以及常规元素都有一个开始标签来表示开始,一个结束标签来表示结束。
- 某些元素的开始和结束标签是可以省略的,如果规定标签不能被省略,那么就绝对不能省略它。
- 空元素只有一个开始标签,且不能为空元素设置结束标签。
- 外来元素可以有一个开始标签和配对的结束标签,或者只有一个自闭合的开始标签,且后者情况下该元素不能有结束标签。
推荐:
<div>
<h1>我是h1标题</h1>
<p>我是一段文字,我有始有终,浏览器能正确解析</p>
</div>
<br>
不推荐:
<div>
<h1>我是h1标题</h1>
<p>我是一段文字,我有始无终,浏览器亦能正确解析
</div>
<br/>
书写风格
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>
元素属性
元素属性值使用双引号语法
元素属性值可以写上的都写上
推荐:
<input type="text">
<input type="radio" name="name" checked="checked" >
不推荐:
<input type=text>
<input type='text'>
<input type="radio" name="name" checked >
特殊字符的应用
文本可以和字符引用混合出现。这种方法可以用来转义在文本中不能合法出现的字符。
推荐:
<a href="#">more>></a>
不推荐:
<a href="#">more>></a>
更多关于符号引用:#Character references
代码缩进
统一使用四个空格进行代码缩进,使得各编辑器表现一致(各编辑器有相关配置)
<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>
注释规范
标准写法:
<!--Comment Text-->
单行注释:一般用于简单的描述,如某些状态描述、属性描述等(注释内容前后各一个空格字符,注释位于要注释代码的上面,单独占一行)
推荐:
<!-- 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 -->
文件模板
HTML模版指的是团队使用的初始化HTML文件,里面会根据不同平台而采用不一样的设置,一般主要不同的设置就是 mata 标签的设置,以下是 PC 和移动端的 HTML 模版。
HTML5标准模版
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>HTML5标准模版</title>
</head>
<body>
</body>
</html>
移动端
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, shrink-to-fit=no" >
<meta name="format-detection" content="telephone=no" >
<title>移动端HTML模版</title>
<!-- S DNS预解析 -->
<link rel="dns-prefetch" href="">
<!-- E DNS预解析 -->
<!-- S 线上样式页面片,开发请直接取消注释引用 -->
<!-- #include virtual="" -->
<!-- E 线上样式页面片 -->
<!-- S 本地调试,根据开发模式选择调试方式,请开发删除 -->
<link rel="stylesheet" href="css/index.css" >
<!-- /本地调试方式 -->
<link rel="stylesheet" href="http://srcPath/index.css" >
<!-- /开发机调试方式 -->
<!-- E 本地调试 -->
</head>
<body>
</body>
</html>
PC端
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="keywords" content="your keywords">
<meta name="description" content="your description">
<meta name="author" content="author,email address">
<meta name="robots" content="index,follow">
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
<meta name="renderer" content="ie-stand">
<title>PC端HTML模版</title>
<!-- S DNS预解析 -->
<link rel="dns-prefetch" href="">
<!-- E DNS预解析 -->
<!-- S 线上样式页面片,开发请直接取消注释引用 -->
<!-- #include virtual="" -->
<!-- E 线上样式页面片 -->
<!-- S 本地调试,根据开发模式选择调试方式,请开发删除 -->
<link rel="stylesheet" href="css/index.css" >
<!-- /本地调试方式 -->
<link rel="stylesheet" href="http://srcPath/index.css" >
<!-- /开发机调试方式 -->
<!-- E 本地调试 -->
</head>
<body>
</body>
</html>
图片格式
常见的图片格式有 GIF、PNG8、PNG24、JPEG、WEBP,根据图片格式的特性和场景需要选取适合的图片格式。
GIF(一般用作动图,不适合图片)
优秀的压缩算法使其在一定程度上保证图像质量的同时将体积变得很小。
可插入多帧,从而实现动画效果。
可设置透明色以产生对象浮现于背景之上的效果。
由于采用了8位压缩,最多只能处理256种颜色,故不宜应用于真彩色图片。
PNG
支持256色调色板技术,文件体积小。
无损压缩
最高支持48位真彩色图像以及16位灰度图像。
支持Alpha通道的透明/半透明特性。
支持图像亮度的Gamma校准信息。
支持存储附加文本信息,以保留图像名称、作者、版权、创作时间、注释等信息。
渐近显示和流式读写,适合在网络传输中快速显示预览效果后再展示全貌。
使用CRC防止文件出错。
最新的PNG标准允许在一个文件内存储多幅图像。
JPEG
适用于储存24位元全采影像
采取的压缩方式通常为有损压缩
不支持透明或动画
压缩比越高影像耗损越大,失真越严重
压缩比在10左右肉眼无法分辨出压缩图与原图的差别
WEBP
同时提供有损压缩和无损压缩两种图片文件格式
文件体积小,无损压缩后,比 PNG 文件少了 45% 的文件大小;有损压缩后,比 JPEG 文件少了 25% - 34% 文件大小
浏览器兼容差,目前只支持客户端 Chrome 和 Opera 浏览器以及安卓原生浏览器(Andriod 4.0+)
如何采用:
内容图:
优先考虑 JPEG 格式,条件允许的话优先考虑 WebP 格式
背景图:
PNG 与 GIF 格式,优先考虑使用 PNG 格式,PNG格式允许更多的颜色并提供更好的压缩率
图片引入
HTML 中图片引入不需添加 width、height 属性,alt 属性应该写上
推荐:
<img src="" alt="" >
不推荐:
<img src="" width="" height="" >
CSS 中图片引入不需要引号
z.jdc {
background-image: url(icon.png);
}
CSS规范
代码格式化(建议采用展开型,建议统一采用小写方式,每个属性声明末尾必须加分号 ; )
紧凑型:
.jdc{ display: block;width: 50px;}
展开型:
.jdc{
display: block;
width: 50px;
}
选择器
尽量少用通用选择器
不使用 ID 选择器
不使用无具体语义定义的标签选择器
/* 推荐 */
.jdc {}
.jdc li {}
.jdc li p{}
/* 不推荐 */
*{}
#jdc {}
.jdc div{}
属性书写方式
布局定位属性: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;
}
浏览器私有前置写法
CSS3 浏览器私有前缀在前,标准前缀在后
.jdc {
-webkit-border-radius: 10px;
-moz-border-radius: 10px;
-o-border-radius: 10px;
-ms-border-radius: 10px;
border-radius: 10px;
}
命名规范
目录命名
项目文件夹:projectname
样式文件夹:css
脚本文件夹:js
样式类图片文件夹:img
图片命名(图片业务(可选) +(mod_)图片功能类别(必选)+ 图片模块名称(可选) + 图片精度(可选))
图片业务:
pp_:拍拍
wx_:微信
sq_:手Q
jd_:京东商城
…
图片功能类别:
mod_:是否公共,可选
icon:模块类固化的图标
logo:LOGO类
spr:单页面各种元素合并集合
btn:按钮
bg:可平铺或者大背景
…
图片模块名称:
goodslist:商品列表
goodsinfo:商品信息
userava tar:用户头像
…
图片精度:
普清:@1x
Retina:@2x | @3x
…
HTML/CSS命名
确保文件命名总是以字母开头而不是数字,且字母一律小写,以下划线连接且不带其他标点符号,如:
<!-- HTML -->
jdc.html
jdc_list.html
jdc_detail.html
<!-- SASS -->
jdc.scss
jdc_list.scss
jdc_detail.scss
ClassName命名
ClassName的命名应该尽量精短、明确,必须以字母开头命名,且全部字母为小写,单词之间统一使用下划线 “_” 连接
基于姓氏命名法(继承 + 外来)
<div class="modulename">
<div class="modulename_info">
<div class="modulename_son"></div>
<div class="modulename_son"></div>
...
</div>
</div>
<!-- 这个是全站公用模块,祖先模块允许直接出现下划线 -->
<div class="mod_info">
<div class="mod_info_son"></div>
<div class="mod_info_son"></div>
...
</div>
不推荐:
<div class="modulename_info">
<div class="modulename_info_son"></div>
<div class="modulename_info_son"></div>
...
</div>
在子孙模块数量可预测的情况下,严格继承祖先模块的命名前缀
<div class="modulename">
<div class="modulename_cover"></div>
<div class="modulename_info"></div>
</div>
当子孙模块超过4级或以上的时候,可以考虑在祖先模块内具有识辨性的独立缩写作为新的子孙模块
推荐:
<div class="modulename">
<div class="modulename_cover"></div>
<div class="modulename_info">
<div class="modulename_info_user">
<div class="modulename_info_user_img">
<img src="" alt="">
<!-- 这个时候 miui 为 modulename_info_user_img 首字母缩写-->
<div class="miui_tit"></div>
<div class="miui_txt"></div>
...
</div>
</div>
<div class="modulename_info_list"></div>
</div>
</div>
不推荐:
<div class="modulename">
<div class="modulename_cover"></div>
<div class="modulename_info">
<div class="modulename_info_user">
<div class="modulename_info_user_img">
<img src="" alt="">
<div class="modulename_info_user_img_tit"></div>
<div class="modulename_info_user_img_txt"></div>
...
</div>
</div>
<div class="modulename_info_list"></div>
</div>
</div>
模块命名
全站公共模块:以 mod_ 开头
<div class="mod_yours"></div>
业务公共模块:以 业务名mod 开头
<div class="paipai_mod_yours"></div>
常用命名推荐
注意:ad、banner、gg、guanggao 等有机会和广告挂勾的字眠不建议直接用来做ClassName,因为有些浏览器插件(Chrome的广告拦截插件等)会直接过滤这些类名
ClassName 含义
about 关于
account 账户
arrow 箭头图标
article 文章
aside 边栏
audio 音频
avatar 头像
bg,background 背景
bar 栏(工具类)
branding 品牌化
crumb,breadcrumbs 面包屑
btn,button 按钮
caption 标题,说明
category 分类
chart 图表
clearfix 清除浮动
close 关闭
col,column 列
comment 评论
community 社区
container 容器
content 内容
copyright 版权
current 当前态,选中态
default 默认
description 描述
details 细节
disabled 不可用
entry 文章,博文
error 错误
even 偶数,常用于多行列表或表格中
fail 失败(提示)
feature 专题
fewer 收起
field 用于表单的输入区域
figure 图
filter 筛选
first 第一个,常用于列表中
footer 页脚
forum 论坛
gallery 画廊
group 模块,清除浮动
header 页头
help 帮助
hide 隐藏
hightlight 高亮
home 主页
icon 图标
info,information 信息
last 最后一个,常用于列表中
links 链接
login 登录
logout 退出
logo 标志
main 主体
menu 菜单
meta 作者、更新时间等信息栏,一般位于标题之下
module 模块
more 更多(展开)
msg,message 消息
nav,navigation 导航
next 下一页
nub 小块
odd 奇数,常用于多行列表或表格中
off 鼠标离开
on 鼠标移过
output 输出
pagination 分页
pop,popup 弹窗
preview 预览
previous 上一页
primary 主要
progress 进度条
promotion 促销
rcommd,recommendations 推荐
reg,register 注册
save 保存
search 搜索
secondary 次要
section 区块
selected 已选
share 分享
show 显示
sidebar 边栏,侧栏
slide 幻灯片,图片切换
sort 排序
sub 次级的,子级的
submit 提交
subscribe 订阅
subtitle 副标题
success 成功(提示)
summary 摘要
tab 标签页
table 表格
txt,text 文本
thumbnail 缩略图
time 时间
tips 提示
title 标题
video 视频
wrap 容器,包,一般用于最外层
wrapper 容器,包,一般用于最外层
JS规范
语言规范
基本类型
字符串
数值
布尔类型
null
undefined
const foo = 1
let bar = foo
bar = 9
console.log(foo, bar) // 1, 9
复杂数据类型
object
array
function
const foo = [1, 2, 3]
const bar = foo
bar[0] = 9
console.log(foo[0], bar[0]) // 9, 9
引用(const声明常量,let声明变量)
const 和 let 都是块级作用域,var 是函数级作用域
对所有引用都使用 const,不要使用 var
// bad
var a = 1
var b = 2
// good
const a = 1
const b = 2
如果引用是可变动的,则使用 let
// bad
var count = 1
if (count < 10) {
count += 1
}
// good
let count = 1
if (count < 10) {
count += 1
}
对象
请使用字面量值创建对象
// bad
const a = new Object{}
// good
const a = {}
别使用保留字作为对象的键值,这样在 IE8 下不会运行
// bad
const a = {
default: {}, // default 是保留字
common: {}
}
// good
const a = {
defaults: {},
common: {}
}
请使用对象方法的简写方式
// bad
const item = {
value: 1,
addValue: function (val) {
return item.value + val
}
}
// good
const item = {
value: 1,
addValue(val) {
return item.value + val
}
}
请使用对象属性值的简写方式
const job = 'FrontEnd'
// bad
const item = {
job: job
}
// good
const item = {
job
}
对象属性值的简写方式要和声明式的方式分组
const job = 'FrontEnd'
const department = 'JDC'
// bad
const item = {
sex: 'male',
job,
age: 25,
department
}
// good
const item = {
job,
department,
sex: 'male',
age: 25
}
数组
请使用字面量值创建数组
// bad
const items = new Array()
// good
const items = []
向数组中添加元素时,请使用 push 方法
const items = []
// bad
items[items.length] = 'test'
// good
items.push('test')
使用拓展运算符 ... 复制数组
// bad
const items = []
const itemsCopy = []
const len = items.length
let i
// bad
for (i = 0; i < len; i++) {
itemsCopy[i] = items[i]
}
// good
itemsCopy = [...items]
解构赋值
当需要使用对象的多个属性时,请使用解构赋值
// bad
function getFullName (user) {
const firstName = user.firstName
const lastName = user.lastName
return `${firstName} ${lastName}`
}
// good
function getFullName (user) {
const { firstName, lastName } = user
return `${firstName} ${lastName}`
}
// better
function getFullName ({ firstName, lastName }) {
return `${firstName} ${lastName}`
}
当需要使用数组的多个值时,请同样使用解构赋值
const arr = [1, 2, 3, 4]
// bad
const first = arr[0]
const second = arr[1]
// good
const [first, second] = arr
函数需要回传多个值时,请使用对象的解构,而不是数组的解构
// bad
function doSomething () {
return [top, right, bottom, left]
}
// 如果是数组解构,那么在调用时就需要考虑数据的顺序
const [top, xx, xxx, left] = doSomething()
// good
function doSomething () {
return { top, right, bottom, left }
}
// 此时不需要考虑数据的顺序
const { top, left } = doSomething()
字符串
字符串统一使用单引号的形式 ''
// bad
const department = "JDC"
// good
const department = 'JDC'
字符串太长的时候,请不要使用字符串连接符换行 \,而是使用 +
const str = '凹凸实验室 凹凸实验室 凹凸实验室' +
'凹凸实验室 凹凸实验室 凹凸实验室' +
'凹凸实验室 凹凸实验室'
程序化生成字符串时,请使用模板字符串
const test = 'test'
// bad
const str = ['a', 'b', test].join()
// bad
const str = 'a' + 'b' + test
// good
const str = `ab${test}`
函数
请使用函数声明,而不是函数表达式
// bad
const foo = function () {
// do something
}
// good
function foo () {
// do something
}
不要在非函数代码块中声明函数
// bad
if (isUse) {
function test () {
// do something
}
}
// good
let test
if (isUse) {
test = () => {
// do something
}
}
不要使用 arguments,可以选择使用 ...
arguments 只是一个类数组,而 ... 是一个真正的数组
// bad
function test () {
const args = Array.prototype.slice.call(arguments)
return args.join('')
}
// good
function test (...args) {
return args.join('')
}
不要更改函数参数的值
// bad
function test (opts) {
opts = opts || {}
}
// good
function test (opts = {}) {
// ...
}
模块
使用标准的 ES6 模块语法 import 和 export
// bad
const util = require('./util')
module.exports = util
// good
import Util from './util'
export default Util
// better
import { Util } from './util'
export default Util
不要使用 import 的通配符 *,这样可以确保你只有一个默认的 export
// bad
import * as Util from './util'
// good
import Util from './util'
对象属性
使用 . 来访问对象属性
const joke = {
name: 'haha',
age: 28
}
// bad
const name = joke['name']
// good
const name = joke.name
代码规范
单行代码块(在单行代码块中使用空格)
不推荐
function foo () {return true}
if (foo) {bar = 0}
推荐
function foo () { return true }
if (foo) { bar = 0 }
大括号风格(建议使用第一种)
One True Brace Style
if (foo) {
bar()
} else {
baz()
}
Stroustrup
if (foo) {
bar()
}
else {
baz()
}
Allman
if (foo)
{
bar()
}
else
{
baz()
}
变量命名(建议使用 驼峰式)
当命名变量时,主流分为驼峰式命名(variableName)和下划线命名(variable_name)两大阵营。
拖尾逗号(建议最后一个字面量可以不加拖尾逗号)
在 ECMAScript5 里面,对象字面量中的拖尾逗号是合法的,但在 IE8(非 IE8 文档模式)下,当出现拖尾逗号,则会抛出错误。
var foo = {
name: 'foo',
age: '22',
}
逗号空格
逗号前后的空格可以提高代码的可读性
不推荐
var foo = 1,bar = 2
var foo = 1 , bar = 2
var foo = 1 ,bar = 2
推荐
var foo = 1, bar = 2
逗号风格
标准风格,逗号放置在当前行的末尾
逗号前置风格,逗号放置在下一行的开始位置
不推荐
var foo = 1
,
bar = 2
var foo = 1
, bar = 2
var foo = ['name'
, 'age']
推荐
var foo = 1,
bar = 2
var foo = ['name',
'age']
计算属性空格
不推荐
obj['foo' ]
obj[ 'foo']
obj[ 'foo' ]
推荐
obj['foo']
构造函数首字母大写
不推荐
var fooItem = new foo()
推荐
var fooItem = new Foo()