前端代码规范文档（Vue、es6、ts、部分js）

Vue 开发规范目录及说明

• 规范目的
• 命名规范
• 结构化规范
• 注释规范
• 编码规范
• CSS 规范

规范目的

为提高团队协作效率，便于后台人员添加功能及前端后期项目有何迭代，以及提高自身代码质量，让大家书写可维护的代码，而不是一次性的代码，让代码能一目了然，业务逻辑实现表达清晰

命名规范

• 普通变量命名规范

命名方法 ： 驼峰命名法

命名规范 ：

 

命名必须是跟需求的内容相关的词，比如说我想申明一个 变量 ，用来表示我的学校，那么我们可以这样定义  const mySchool = "我的学校";

 

命名是复数的时候需要加 s ,比如说我想申明一个 数组 ，表示很多人的名字，那么我们可以这样定义  const names = new Array();

 

 

• 常量命名规范

命名方法 : 全部大写

命名规范 : 使用大写字母和下划线来组合命名，下划线用以分割单词

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

注意：谨慎使用下划线 _前端中下划线_一般作为特殊使用的下划线，比如常量中作为语义分隔(MAX_VALUE)，前置作为私有不能使用的变量(__myprovite)。

• 全局变量

在利用模块化变成以后，全局变量用得比较少了，但在VM输出的变量都是全局变量，全局变量的命名方法一般是g+变量名。

var gConfig = {
   name:1,
   desc:2，
   roles:[]
};

• 方法命名规范

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

//bad
go、nextPage、show、open、login

// good
jumpPage、openCarInfoDialog

init、refresh 单词除外

注意：尽量使用常用单词开头（set、get、go、can、has、is），不强求动名词的使用限制，但是必须词语必须能表达除含义

函数方法常用的动词，请查看附录1.1

• 组件命名规范

官方文档推荐及使用遵循规则：

PascalCase (单词首字母大写命名)是最通用的声明约定

kebab-case (短横线分隔命名) 是最通用的使用约定

组件名应该始终是多个单词的，根组件 App 除外

有意义的名词、简短、具有可读性

1. 命名遵循 PascalCase 约定

   公用组件以 Abcd (公司名缩写简称) 开头，如（AbcdDatePicker,AbcdTable）

   页面内部组件以组件模块名简写为开头，Item 为结尾，如（StaffBenchToChargeItem，StaffBenchAppNotArrItem）

2. 使用遵循 kebab-case 约定

在页面中使用组件需要前后闭合，并以短线分隔，如（，）

导入及注册组件时，遵循 PascalCase 约定

同时还需要注意：必须符合自定义元素规范: 切勿使用保留字。

为代码统一美观组件全部用kebab-case  如：car-item、product-list-item、product-detail

Vue.component('my-component', {});

 

• views下文件命名规范

只有一个文件的情况下不会出现文件夹，而是直接放在 views 目录下面，如 index.vue

尽量是名词,且使用驼峰命名法

开头的单词就是所属模块名字（workbenchIndex、workbenchList、workbenchEdit）

名字至少两个单词（good: workbenchIndex）（bad:workbench）

• props 命名

例外情况

作用域不大临时变量可以简写，比如：str，num，bol，obj，fun，arr。

循环变量可以简写，比如：i，j，k 等。

•  

 

• 注意：谨慎使用下划线 _前端中下划线_一般作为特殊使用的下划线，比如常量中作为语义分隔(MAX_VALUE)，前置作为私有不能使用的变量(__myprovite)。

例外情况

 

结构化规范

目录文件夹及子文件规范

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

```bash
├── mock                       # mock 服务器 与 模拟数据
├── public                     # 静态资源 (会被直接复制)
│   │── favicon.ico            # favicon图标
│   │── manifest.json          # PWA 配置文件
│   └── index.html             # html模板
├── src                        # 源代码
│   ├── api                    # 所有请求
│   ├── assets                 # 主题 字体等静态资源 (由 webpack 处理加载)
│   ├── components             # 全局组件
│   ├── directive              # 全局指令
│   ├── filters                # 全局过滤函数
│   ├── icons                  # svg 图标
│   ├── lang                   # 国际化
│   ├── layout                 # 全局布局
│   ├── pwa                    # PWA service worker 相关的文件
│   ├── router                 # 路由
│   ├── store                  # 全局 vuex store
│   ├── styles                 # 全局样式
│   ├── utils                  # 全局方法
│   ├── views                  # 所有页面
│   ├── App.vue                # 入口页面
│   ├── main.js                # 入口文件 加载组件 初始化等
│   ├── permission.ts          # 权限管理
│   ├── settings.ts            # 设置文件
│   └── shims.d.ts             # 模块注入
├── tests                      # 测试
├── .circleci/                 # 自动化 CI 配置
├── .browserslistrc            # browserslistrc 配置文件 (用于支持 Autoprefixer)
├── .editorconfig              # 编辑相关配置
├── .env.xxx                   # 环境变量配置
├── .eslintrc.js               # eslint 配置
├── babel.config.js            # babel-loader 配置
├── cypress.json               # e2e 测试配置
├── jest.config.js             # jest 单元测试配置
├── package.json               # package.json 依赖
├── postcss.config.js          # postcss 配置
├── tsconfig.json              # typescript 配置
└── vue.config.js              # vue-cli 配置

vue 文件基本结构

js

  
  
  
  
复制代码

 

ts

/**
* @Notes:
* @Author: liuyuquan
* Date: 2020/11/28 15:03
*/

组件周期函数顺序（vue2）

  - components
  - props
  - data
  - computed

   - watch
  - created
  - mounted
  - filter

注释规范

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

务必添加注释列表

1. 公共组件使用说明

2. 各组件中重要函数或者类说明

3. 复杂的业务逻辑处理说明

4. 特殊情况的代码处理说明,对于代码中特殊用途的变量、存在临界值、函数中使用的 hack、使用了某种算法或思路等需要进行注释描述

5. 多重 if 判断语句

6. 注释块必须以/**（至少两个星号）开头**/

7. 单行注释使用//

单行注释

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

  bad
 
  var name =”abc”; // 姓名    
 
  good
 
  // 姓名
  var name = “abc”;         
复制代码

多行注释

仅为示例，注释必要要求  需要有 作者 时间 组件描述即可

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

 

编码规范

优秀的项目源码，即使是多人开发，看代码也如出一人之手。统一的编码规范，可使代码更易于阅读，易于理解，易于维护。尽量按照 ESLint 格式要求编写代码

源码风格

使用 ES6 风格编码

1、定义变量使用 let ，定义常量使用 const

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

  // 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'
复制代码

 

3、解构赋值

   

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

  // 数组解构赋值
  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 }) {}
复制代码

4、拷贝数组

使用扩展运算符（...）拷贝数组

  const items = [1, 2, 3, 4, 5]
 
  // bad
  const itemsCopy = items
 
  // good
  const itemsCopy = [...items]
复制代码

5、箭头函数

需要使用函数表达式的场合，尽量用箭头函数代替。因为这样更简洁，而且绑定了 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);
复制代码

6、模块

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

  // bad
  import * as myObject from './importModule'
 
  // good
  import myObject from './importModule'
复制代码

CSS 规范

通用规范

1、统一使用"-"连字符

2、省略值为 0 时的单位

 // bad
  padding-bottom: 0px;
  margin: 0em;
 
 // good
  padding-bottom: 0;
  margin: 0;
复制代码

3、如果 CSS 可以做到，就不要使用 JS

4、建议并适当缩写值，提高可读性，特殊情况除外

“建议并适当”是因为缩写总是会包含一系列的值，而有时候我们并不希望设置某一值，反而造成了麻烦，那么这时候你可以不缩写，而是分开写。

当然，在一切可以缩写的情况下，请务必缩写，它最大的好处就是节省了字节，便于维护，并使阅读更加一目了然。

  // 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;
  }
复制代码

5、声明应该按照下表的顺序

左到右，从上到下

显示属性	自身属性	文本属性和其他修饰
display	width	font
visibility	height	text-align
position	margin	text-decoration
float	padding	vertical-align
clear	border	white-space
list-style	overflow	color
top	min-width	background

  // bad
  .box {
    font-family: 'Arial', sans-serif;
    border: 3px solid #ddd;
    left: 30%;
    position: absolute;
    text-transform: uppercase;
    background-color: #eee;
    right: 30%;
    isplay: block;
    font-size: 1.5rem;
    overflow: hidden;
    padding: 1em;
    margin: 1em;
  }
 
  // good
  .box {
    display: block;
    position: absolute;
    left: 30%;
    right: 30%;
    overflow: hidden;
    margin: 1em;
    padding: 1em;
    background-color: #eee;
    border: 3px solid #ddd;
    font-family: 'Arial', sans-serif;
    font-size: 1.5rem;
    text-transform: uppercase;
  }
复制代码

补充：

指令规范

1、指令有缩写一律采用缩写形式

  // bad
  v-bind:class="{'show-left'：true}"
  v-on:click="getListData"
 
  // good
  :class="{'show-left'：true}"
  @click="getListData"
复制代码

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

  
  

    

      {{ todo.text }}
    
  
 
  
  

    

      {{ todo.text }}
    
  
复制代码

3、避免 v-if 和 v-for 同时用在一个元素上（性能问题）

以下为两种解决方案：

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

  
  

    

      {{ user.name }}
    
  
 
  
  

    

      {{ user.name }}
    
  
 
  
复制代码

其他

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);
复制代码

附录1.1

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 聚集
复制代码