此文档适用于编写基于Vimo的前端项目, 涵盖了JavaScript/Scss/Html/Vue四个部分.
JavaScript代码的规范参考Standard Code Style
JavaScript风格百家争鸣, 这里统一使用Standard Code Style, 其中Webstorm自带此规范, 且能自动修正不符合规范的地方, 较为方便.
在代码中使用严格模式
'use strict';，详细参考javascript严格模式详解。
'use strict';
arr1 = new Array(); // Error
var arr2 = new Array(); // Successjs全部使用单引号
''，拼html模板内使用双引号""。
// bad
var param = "string";
var html = head + "<div class='main' data-id='main'></div>" + footer;
// good
var param = 'string';
var html = head + '<div class="main" data-id="main"></div>' + footer;虽然js行末的分号不是必须的，但是为了代码风格统一，以及避免打包压缩带来的不可预测问题（真正会导致上下行解析出问题的token有5个：括号，方括号，正则开头的斜杠，加号，减号。一行开头是括号或者方括号的时候不添加分号会报错。），每行末的分号不可以省略。
js分号工具semi
// bad
var html = head + "<div class='main' data-id='main'></div>" + footer
alert(html)
// error
var num = 1
(function() {
console.log(num)
})
var str = 'error message'
// good
var html = head + '<div class="main" data-id="main"></div>' + footer;
alert(html);js变量命名使用小驼峰命名法，按照类型进行区分，需要突出属性特征、用途，不要使用不能清晰表达意义的缩略词。
- 普通对象
// bad
var lib-name = 'sammy.js';
var lib_name = 'sammy.js';
var LibName = 'sammy.js';
// good
var libName = 'sammy.js';- jQuery对象：
统一添加 $ 作为命名前缀，突出为jQuery对象
// bad
var slider = $('#slider');
var side-bar = $('#sideBar');
var side_bar = $('#sideBar');
// good
var $slider = $('#slider');
var $sideBar = $('#sideBar');- 函数：
小驼峰写法，中间无中横线或者下横线
// bad
function get_name() {}
function get-name() {}
// good
function getName() {}- 类(构造函数声明)：
首字母需要大写，驼峰写法
// bad
function superClass() {}
// good
function SuperClass() {}- 缩写词需要准确表明意义
// bad
var comm = document.getElementById('#comment');
// good
var comment = document.getElementById('#comment');variableNamesLikeThisfunctionNamesLikeThisfunctionArgumentsLikeThisClassNamesLikeThisEnumNamesLikeThismethodNamesLikeThisCONSTANTS_LIKE_THISnamespacesLikeThisprivateorprotected属性和方法需要在前面加上_前缀- 不应该使用短名称或者有歧义的名称
- 常用的缩略语, 比如
JSON和XML写成CamelCase格式. 例如:Json,Xml.
空格与tap不能混用。如果使用空格，四个空格代替一个缩进的位置。如果使用tap，请设置一个tap代替四个空格的位置长度。
建议项目全部使用Scss格式编写, 并且使用BEM的书写风格
建议采用OOCSS的思想编写样式文件, BEM是一个样式编写规范, 这里介绍了它的命名规范. 简要的说, 其将一个元素或者结构分为三级结构:
block__element--modifierblock__element--modifier-other
因此, 按照规范, 编写及后续维护都将不再困难.
- name
.block
- html
<div class="block">...</div>- css
.block { color: #042; }- name
.block__elem
- html
<div class="block">
...
<span class="block__elem"></span>
</div>- css
.block__elem { color: #042; }- name
// 一层修饰符
.block--mod
.block__elem--mod
// 两层修饰符
.block--color-black
.block--color-red.
- html
<div class="block block--mod">...</div>
<div class="block block--size-big block--shadow-yes">...</div>- css
.block__elem--mod { }小驼峰写法，中间无中横线或者下横线。
/* bad */
#Logo { xxx }
#header_logo { xxx }
#header-logo { xxx }
#HeaderLogo { xxx }
/* good */
#logo { xxx }
#headerLogo { xxx }
#headerLogoWrap { xxx }禁止为元素定义无样式的class，而作为调用脚本使用。这样会造成页面class定义冗余以及增加维护难度。请使用元素自带属性或自定义属性实现。
// bad
<div class="click-alert"></div>
$('.click-alert').click(function() {});
// good
<div data-action="clickAlert"></div>
$('div[data-action="clickAlert"]').click(function() {});使用
utf-8编码方式，指定字符编码的meta必须是head的第一个子元素，原因详解。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
...
</hed>
<body>
...
</body>
</html>
title必须作为head的直接子元素，并紧随charset声明之后。title中如果包含ascii之外的字符，浏览器需要知道字符编码类型才能进行解码，否则可能导致乱码。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>标题</title>
...
</hed>
<body>
...
</body>
</html>一个页面只能有一个h1标签，具体与seo有关。
<!-- bad -->
<h1>我是标题一</h1>
<h1>我是标题二</h1>
<!-- good -->
<h1>我是标题一</h1>
<h2>我是标题二</h2>
...
<h6>我是标题六</h6>html标签包含块级元素、内联元素，元素的类型决定嵌套的规则。
常见块元素：div、section、ul、li、p、h1~h6等。
常见内联元素：span、a、i、input、label、img等。
- 常见嵌套
<!-- right：块级元素可以内嵌其他块级元素或者内联元素 -->
<div><h1><span></span></h1></div>
<!-- right：内联元素可以内嵌其他内联元素 -->
<a href=""><span></span></a>- 错误嵌套
<!-- wrong：内联元素不能嵌套其他块级元素 -->
<span><div></div></span>
<!-- wrong：p元素不能内嵌块级元素，类似元素有h1、h2、h3、h4、h5、h6、p、dt -->
<p><div></div></p>
<h1><div></div></h1>
...
<h6><div></div></h6>
<!-- wrong：a标签不能内嵌a标签，这个错误会经常发生，值得重视 -->
<a href="a.html"><a href="a.html"></a></a>- 回退
<!-- right：内联元素内嵌块级元素 -->
<a style="display: block;" href=""><div></div></a>*.vue文件是以上三者(JavaScript/Scss/Html)的组合, 使用规范雷同, 不同部分下面列出:
<template>
<Page>
<Header>
<Navbar>
<Title>Title</Title>
</Navbar>
</Header>
<Content padding class="outer-content">
<p>Content</p>
</Content>
</Page>
</template>
<style scoped lang="scss">
</style>
<script type="text/javascript">
export default{
name: 'name',
data(){
return {}
},
props: {},
watch: {},
computed: {},
methods: {},
created () {},
mounted () {},
activated () {},
components: {}
}
</script>建议：template style script 的顺序书写
<template></template>
<style></style>
<script></script>- style中需要加上
scoped属性标识css的作用域
使用简写模式结构比较清晰
<!-- bad -->
<a v-on:click="pass()">pass</a>
<!-- good -->
<a @click="pass">pass</a>
### JavaScript部分
- script需要加上type类型, 因为Webstorm的自动格式化需要这个标记
- name属性必填, 便于Devtool的定位
```javascript
import myComponentsA from './myComponentsA.vue'
import myComponentsB from './myComponentsB.vue'
import myComponentsC from './myComponentsC.vue'
import myComponentsD from './myComponentsD.vue'
export default {
components: {
myComponentsA,
myComponentsB,
myComponentsC,
myComponentsD,
}
}事件绑定部分示例, 如果没有特殊的命名则使用对应格式的命名方式:
- @click -> clickHandler
- @onSelect -> onSelectHandler
<p @click="clickHandler">Content</p>
<Select @onSelect="onSelectHandler"><Select>除非必须, 否则不缓存this变量, 作用域的问题使用箭头函数解决(=>)
- 如果用ref获取组件实例, 需要在名称后面加
Component, 例如selectComponent
<template>
<Select ref="select"></Select>
</template>
<script type="text/javascript">
export default {
computed: {
selectComponent(){
return this.$refs.select
}
}
}
</script>- 如果用ref获取元素, 需要在名称后面加
Element, 例如selectElement
<template>
<p ref="select">Hello</p>
</template>
<script type="text/javascript">
export default {
computed: {
selectElement(){
return this.$refs.select
}
}
}
</script>_前缀是内部变量, 不建议在vue文件中定义, 直接使用普通名称就好
在编写组件时, 有时需要缓存props值并进行修改, 比如props中的value需要修改, 缓存值可命名为theValue, 其他缓存的变量命名如下:
- value -> theValue
- disabled -> theDisabled
- duration -> theDuration