Vue前端开发规范

规范的目的是为了提高团队协作，便于功能开发及后期维护，输出高质量的代码

命名规范

普通变量命名规范

• 命名方法：驼峰命名法
• 命名规范：
  1. 命名必须是跟需求内容相关联的词，比如声明一个变量表示我的学校，那么可以定义为const mySchool = "我的学校"
  2. 变量的命名是复数的时候需要加s,比如我想声明一个数组，表示很多人的名字，const names = []

常量命名规范

• 命名方法：全部大写
• 命名规范：使用大写字母和下划线来组合命名，下划线用以分割单词。

const MAX_COUNT = 10
const URL = 'https://www.baidu.com/'

组件命名规范

组件文件

只要有能够拼接文件的构建系统，就把每个组件单独分成文件。

// 反例
Vue.component('TodoList', {
  // ...
})

Vue.component('TodoItem', {
  // ...
})

// 好例子
components/
|- TodoList.vue
|- TodoItem.vue

单文件组件

单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)。

// 反例
components/
|- mycomponent.vue
|- myComponent.vue

// 好例子
components/
|- MyComponent.vue
|- my-component.vue

基础组件名

应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头，比如 Base、App 或 V。

// 反例
components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue

// 好例子
components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue

单例组件

只应该拥有单个活跃实例的组件应该以 The 前缀命名，以示其唯一性。

// 反例
components/
|- Heading.vue
|- MySidebar.vue

// 好例子
components/
|- TheHeading.vue
|- TheSidebar.vue

紧密耦合的组件

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。

components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue

components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue

// 好例子
components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue

components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

组件名中的单词顺序

组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。

// 好例子
components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

Prop命名规范

在声明 prop 的时候，其命名应该始终使用 camelCase，而在模板和 JSX 中应该始终使用 kebab-case。

<!-- bad -->
<script>
props: {
  'greeting-text': String
}
</script>

<welcome-message greetingText="hi"></welcome-message>

<!-- good -->
<script>
props: {
  greetingText: String
}
</script>

<welcome-message greeting-text="hi"></welcome-message>

多个attribute的元素

多个 attribute 的元素应该分多行撰写，每个 attribute 一行。

<!-- bad -->
<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
<MyComponent foo="a" bar="b" baz="c"/>
<!-- good -->
<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

method方法命名规范

• 驼峰式命名，统一使用动词或者动词+名词形式

// bad
go、nextPage、show、open、login
// good
jumpPage、openCarInfoDialog

• 请求数据方法，以data结尾

//bad
takeData、confirmData、getList、postForm

// good
getListData、postFormData

• init、refresh 单词除外
• 尽量使用常用单词开头（set、get、go、can、has、is）

附： 函数方法常用的动词:

get 获取/set 设置,
add 增加/remove 删除
create 创建/destory 移除
start 启动/stop 停止
open 打开/close 关闭,
read 读取/write 写入
load 载入/save 保存,
create 创建/destroy 销毁
begin 开始/end 结束,
backup 备份/restore 恢复
import 导入/export 导出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附着/detach 脱离
bind 绑定/separate 分离,
view 查看/browse 浏览
edit 编辑/modify 修改,
select 选取/mark 标记
copy 复制/paste 粘贴,
undo 撤销/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 减少
play 播放/pause 暂停,
launch 启动/run 运行
compile 编译/execute 执行,
debug 调试/trace 跟踪
observe 观察/listen 监听,
build 构建/publish 发布
input 输入/output 输出,
encode 编码/decode 解码
encrypt 加密/decrypt 解密,
compress 压缩/decompress 解压缩
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 连接/disconnect 断开,
send 发送/receive 接收
download 下载/upload 上传,
refresh 刷新/synchronize 同步
update 更新/revert 复原,
lock 锁定/unlock 解锁
check out 签出/check in 签入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展开/collapse 折叠
begin 起始/end 结束,
start 开始/finish 完成
enter 进入/exit 退出,
abort 放弃/quit 离开
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集

结构化规范

目录文件夹及子文件规范

• 以下统一管理处均对应相应模块
• 以下全局文件文件均以 index.js 导出，并在 main.js 中导入
• 以下临时文件，在使用后，接口已经有了，发版后清除

src                               源码目录
|-- api                              接口，统一管理
|-- assets                           静态资源，统一管理
|-- components                       公用组件，全局文件
|-- filters                          过滤器，全局工具
|-- icons                            图标，全局资源
|-- datas                            模拟数据，临时存放
|-- lib                              外部引用的插件存放及修改文件
|-- mock                             模拟接口，临时存放
|-- router                           路由，统一管理
|-- store                            vuex, 统一管理
|-- views                         视图目录
|   |-- staffWorkbench               视图模块名
|   |-- |-- staffWorkbench.vue       模块入口页面
|   |-- |-- indexComponents          模块页面级组件文件夹
|   |-- |-- components               模块通用组件文件夹

注释规范

代码注释在一个项目的后期维护中显的尤为重要，所以我们要为每一个被复用的组件编写组件使用说明，为组件中每一个方法编写方法说明

务必添加注释列表

• 公共组件使用说明
• 各组件中重要函数或者类说明
• 复杂的业务逻辑处理说明
• 特殊情况的代码处理说明,对于代码中特殊用途的变量、存在临界值、函数中使用的 hack、使用了某种算法或思路等需要进行注释描述
• 多重 if 判断语句
• 注释块必须以/**（至少两个星号）开头**/
• 单行注释使用 //

单行注释

注释单独一行，不要在代码后的同一行内加注释。例如：

// bad 
const name = "abc" // 姓名

// good

// 姓名
const name = "abc"

多行注释

组件使用说明，和调用说明
 /**
 * 组件名称
 * @module 组件存放位置
 * @desc 组件描述
 * @author 组件作者
 * @date 2017年12月05日17:22:43
 * @param {Object} [title]    - 参数说明
 * @param {String} [columns] - 参数说明
 * @example 调用示例
 *  <hbTable :title="title" :columns="columns" :tableData="tableData"></hbTable>
 **/

编码规范

使用ES6风格编码

定义变量使用 let ,定义常量使用 const

静态字符串一律使用单引号或反引号，动态字符串使用反引号

// bad
const a = 'foobar'
const b = 'foo' + a + 'bar'

// acceptable
const c = `foobar`

// good
const a = 'foobar'
const b = `foo${a}bar`
const c = 'foobar'

结构赋值

• 数组成员对变量赋值时，优先使用解构赋值

// 数组解构赋值
const arr = [1, 2, 3, 4]
// bad
const first = arr[0]
const second = arr[1]

// good
const [first, second] = arr

• 函数的参数如果是对象的成员，优先使用解构赋值

// 对象解构赋值
// bad
function getFullName(user) {
  const firstName = user.firstName
  const lastName = user.lastName
}

// good
function getFullName(obj) {
  const { firstName, lastName } = obj
}

// best
function getFullName({ firstName, lastName }) {}

拷贝数组

使用扩展运算符 (…) 拷贝数组。

const items = [1, 2, 3, 4, 5]

// bad
const itemsCopy = items

// good
const itemsCopy = [...items]

箭头函数

需要使用函数表达式的场合，尽量用箭头函数代替。因为这样更简洁，而且绑定了 this

  // bad
  const self = this;
  const boundMethod = function(...params) {
    return method.apply(self, params);
  }

  // acceptable
  const boundMethod = method.bind(this);

  // best
  const boundMethod = (...params) => method.apply(this, params);

模块

• 如果模块只有一个输出值，就使用 export default，如果模块有多个输出值，就不使用 export default，export default 与普通的 export 不要同时使用

 // bad
 import * as myObject from './importModule'

 // good
 import myObject from './importModule'

• 如果模块默认输出一个函数，函数名的首字母应该小写。

 function makeStyleGuide() {
 }

 export default makeStyleGuide;

• 如果模块默认输出一个对象，对象名的首字母应该大写

 const StyleGuide = {
   es6: {
   }
 };

 export default StyleGuide;

指令规范

指令有所写一律采用缩写

// bad
v-bind:class="{'show-left'：true}"
v-on:click="getListData"

// good
:class="{'show-left'：true}"
@click="getListData"

v-for 循环必须加上key属性，在整个for循环中key需要唯一

 <!-- good -->
 <ul>
   <li v-for="todo in todos" :key="todo.id">
     {{ todo.text }}
   </li>
 </ul>

 <!-- bad -->
 <ul>
   <li v-for="todo in todos">
     {{ todo.text }}
   </li>
 </ul>

避免v-if 和v-for同事用在一个元素上(性能问题)

以下有两种解决方案

1. 将数据替换为一个计算属性，让其返回过滤后的列表

<!-- bad -->
<ul>
  <li v-for="user in users" v-if="user.isActive" :key="user.id">
    {{ user.name }}
  </li>
</ul>

<!-- good -->
<ul>
  <li v-for="user in activeUsers" :key="user.id">
    {{ user.name }}
  </li>
</ul>

<script>
computed: {
  activeUsers: function () {
    return this.users.filter(function (user) {
      return user.isActive
    })
  }
}
</script>

2. 将 v-if 移动至容器元素上 (比如 ul, ol)

<!-- bad -->
<ul>
  <li v-for="user in users" v-if="shouldShowUsers" :key="user.id">
    {{ user.name }}
  </li>
</ul>

<!-- good -->
<ul v-if="shouldShowUsers">
  <li v-for="user in users" :key="user.id">
    {{ user.name }}
  </li>
</ul>

Props规范

Props定义尽量详细

// bad 这样做只有开发原型系统时可以接受
props: ['status']

// good
props: {
  status: {
    type: String,
    required: true,
    validator: function (value) {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].indexOf(value) !== -1
    }
  }
}

其他

1. 避免 this.$parent
2. 调试信息 console.log() debugger 使用完及时删除
3. 除了三目运算，if,else 等禁止简写

// bad
if (true)
  alert(name);
console.log(name);

// bad
if (true)
alert(name);
console.log(name)

// good
if (true) {
  alert(name);
}
console.log(name);

CSS规范

通用规范

• 统一使用中横线"-"连字符
• 省略值为 0 时的单位

 // bad
  padding-bottom: 0px;
  margin: 0em;

 // good
  padding-bottom: 0;
  margin: 0;

• 如果 CSS 可以做到，就不要使用 JS
• 建议并适当缩写值，提高可读性，特殊情况除外

// bad
  .box{
    border-top-style: none;
    font-family: palatino, georgia, serif;
    font-size: 100%;
    line-height: 1.6;
    padding-bottom: 2em;
    padding-left: 1em;
    padding-right: 1em;
    padding-top: 0;
  }

// good
  .box{
    border-top: 0;
    font: 100%/1.6 palatino, georgia, serif;
    padding: 0 1em 2em;
  }

• 元素选择器应该避免在 scoped 中出现
  官方文档说明：在 scoped 样式中，类选择器比元素选择器更好，因为大量使用元素选择器是很慢的。