前端开发规范v1.0

最后一次修订日期：2021/04/12

前言

随着前端工作小组不断有新同事加入，项目开发过程中因个人的编程习惯而产生许多杂乱的、不统一格式的代码，造成项目代码可读性变差，对后期代码的维护和更新造成一定的困难。
为解决以上问题，提高个人和团队的开发效率，共同制定以下开发规范，望大家共同遵守，共同进步。

1. 开发工具和版本规范

针对Vue项目开发，推荐以下工具：

VSCode（日常使用）
HBuilder X （APP和小程序开发时使用）

/* VSCode 推荐插件名称，有其他推荐工具时请共享出来 */
// 中文简体语言包
Chinese (Simplified) Language Pack for Visual Studio Code 

// 使用 Element UI 时推荐使用
Element UI Snippets 

// 快捷工具，使用ctrl+单击 可以快速查找定义的变量和方法，也可以打开文件
vue-helper

// mardown 预览
Markdown Preview Enhanced

// Vue扩展
Vetur
  
//  引入的文件  ctrl+单击 可快捷打开文件
file-jump

开发版本方面，使用Vue2.x,使用vue-cli来便捷创建项目即可。一般使用 vue, vue-router, Vuex全家桶来进行开发。

2. 项目目录规范

依照vue正常的项目目录即可。依赖的本地资源比较大时，需要上传至服务器，异步获取。
请在项目目录中创建readme.md文件，使用此文件来填写项目简介、描述，以及注意事项和一些说明文字，以便于其他同事直观了解本项目内容。【如修改了本地的某个依赖文件，其他同事拉取代码后打包时可能会忽略这个问题，导致生产环境出现问题】

3. 文件命名规范

文件统一使用英文字母命名，统一使用小写字母不使用复数形式，特殊情况下可使用下划线连接符来命名。
文件夹命名时可以使用复数，代表模块时不使用复数。(如 user，views, pages, wallet 文件夹)
首页使用 index, 表单使用 form，详情使用 view来命名，编辑和创建分开时，编辑使用edit，列表优先使用index，也可以使用list/record等。概览或统计图表使用overview。回收站 recycle。

// 例子
|--- views
  |--- goods  // 商城模块
    |--- index.vue  // 商品列表、首页
    |--- cart.vue  // 购物车页面
    |--- view.vue  // 详情

  |--- user  // 用户模块文件夹
    |--- home.vue  // 用户主页页面
    |--- userinfo.vue  // 用户资料页面
    |--- password.vue  // 修改密码页面
    |--- forget.vue  // 找回密码页面
    |--- pay.vue  // 订单支付（收银台）页面
    |--- result.vue  // 支付结果回调页面

  |--- order // 订单模块文件夹
    |--- index.vue  // 订单列表页面
    |--- view.vue  // 订单详情页面
    |--- evaluation.vue  // 订单评价页面
    |--- refund.vue  // 退款申请页面

  |--- common  // 通用模块文件夹
    |--- feedback.vue  // 意见反馈页面
    |--- login.vue  // 登录页面

4. HTML 规范

代码v-for 和 v-if 不要同时在同一个dom上使用，v-if尽量使用在<template>虚拟标签上。

<!-- bad -->
<h3 v-if="show" class="mb-md c3">注册协议</h3> 

<!-- goods-->
<template v-if="show">
  <h3 class="mb-md c3">注册协议</h3>
</template>

属性顺序：
1. 绑定（v-model 、v-if 、v-for）
2. 参数props ( id=1、 :data="v"、:key="k" )
3. 事件、行为（@clicked 、 @changed）
```
// HTML例子
<img v-lazy="v.thumb" class="img" @click="bannerClicked('top', k)" /> 
```

v-if和v-for使用规范

v-if和v-for必须使用template包含。
循环时统一使用v作为值,k作为键使用。如果有多层，第二层循环体使用vv和kk作为键值使用

<template v-for="(v, k) in navList">
  <li :key="k" class="item flex-column p-t-s" @click="navPageTo(v)">
    <template v-for="(vv, kk) in v">
      <span :key="kk">{{vv}}</span>
    </template>
  </li>
</template>

5. CSS 规范

主旨
1. 统一使用"-"连字符
2. 省略值为 0 时的单位。如0.5s设置为.5s
3. 如果 CSS 可以做到，就不要使用 JS
4. 属性使用缩写 border, background 等
5. 优先使用scss,并使用scoped属性，防止局部样式污染全局。
6. 优先使用flex布局，尽量不使用float布局方式。
7. 使用 x , s, m, l 分布代表最小，小，中，大
属性顺序
1. 位置属性 ( position top right z-index display float 等)
2. 大小 ( width height padding margin 等)
3. 文字系列 ( font line-height letter-spacing color text-align 等)
4. 背景 ( background border 等)
5. 其他 ( animation transition 等)
```
.header-user-top {
  position: fixed;
  height: 40px;
  font-size: 14px;
  background-color: rgba(255, 255, 255, .7);
}
```

全局样式的封装与统一使用
会根据公众号H5、小程序端、PC等有不同的common.scss文件。PC端常用10px, 15px, 20px 作为间隔间距。移动端与设计统一，暂定为8px， 16px 作为间隔间距，设计稿宽750px。默认字体为14号大小。

  @each $direction in row, column {
    .flex-#{$direction} {
      display: flex;
      flex-direction: $direction;
      align-items: center;
      &.flex-start {
        justify-content: flex-start;
      }
      &.flex-end {
        justify-content: flex-end;
      }
      &.flex-center {
        justify-content: center;
      }
      &.flex-around {
        justify-content: space-around;
      }
      &.flex-align-start {
        align-items: flex-start;
      }
      &.flex-align-end {
        align-items: flex-end;
      }
    }
  }

// 定义flex等分  flex-1 == flex: 1;
@for $i from 0 through 12 {
  .flex-#{$i} {
      flex: $i;
  }
}

// 定义字体(px)单位，小于20都为px单位字体 font-14 == font-size: 14px
@for $i from 9 to 20 {
  .font-#{$i} {
      font-size: $i + px;
  }
}

// 定义超出截断显示...
.overflow {
  white-space: nowrap;
  text-overflow: ellipsis;
  -o-text-overflow: ellipsis;
  overflow: hidden;
}

// 定义段落最大显示多少行
@for $i from 2 to 10 {
  .clamp-#{$i} {
    display: -webkit-box;
    -webkit-line-clamp: $i;
    -webkit-box-orient: vertical;
    overflow: hidden;
  }
}

$sizes: (
  x: 5,
  s: 10,
  m: 15,
  l: 20
);

@each $key,$val in $sizes {
  .m-#{$key} {
      margin: $val + Px!important;
  }
  .p-#{$key} {
      padding: $val + Px!important;
  }
  @each $short, $long in l left, t top, r right, b bottom {
      .m-#{$short}-#{$key} {
          margin-#{$long}: $val + Px!important;
      }
      .p-#{$short}-#{$key} {
          padding-#{$long}: $val + Px!important;
      }
  }
}

按照以上规范，class命名后，可以直接使用：
m-t-x m-t-l p-s p-b-m m-m
font-14 flex-1 clamp-2
color-primary color-danger color-success
bg-white bg-red bg-warning bg-gray
flex-row flex-column flex-start

6. JS 规范

变量命名
1. 声明变量时，用let代替之前的var，常量务必在<script>下方使用const声明。
2. 常量必须使用大写，用下划线分割。例如:

const USER_KEY = 'CIM_USER'

方法命名
1. 方法要简介，有合适的语义化。统一使用驼峰或下划线分割，不能直接使用单个英文单词作为方法名。
2. 同一个文件中方法名命名格式应统一（即个人可以有自己的习惯，但应保持一致，维护他人代码时也应按照他人之前的格式）。

// 合适的例子
pageToView() {
},
loadData() {
},
reloadData() {
},

// 不合适的例子
page(url) {
},

url(name) {
},

async await 与 promise 的使用规范
1. 默认使用promise封装的axios,包括全局的状态拦截，请求拦截器。返回正常时变量使用res,返回异常时使用变量err
```
this.$axios.get(this.api.village.detail, { params }).then(res => {
  if (res.code == 1) {
    this.villageInfo = res.data;
    this.manager = res.manager;
  }
}, err => {
  console.log(err);
});
```
1. 特殊情况时可使用await，如上传图片时，使用await写法可能更清晰易懂。但应统一按照规范，写好注释。

接口方法名的规范

 // 注释写清楚用途
  vote: {
      user: {
          index: baseUrl + 'vote/user/index', //投票首页,
          join: baseUrl + 'vote/user/join', //报名参与投票
          view: baseUrl + 'vote/user/view', //投票活动详情页
          player: baseUrl + 'vote/user/player',
          vote: baseUrl + 'vote/user/vote',
          rank: baseUrl + 'vote/user/rank',
      }
  },

组件引入和注册
如果仅部分页面引用的插件，不要使用全局注册的方式注册使用。此处列出部分组件，请选择使用：

图片上传压缩组件（设置图片的上传和压缩，图片方向调整等）compressed.js
节流防抖组件（设置一定时间内按钮的响应间隔时间，防止多次触发事件）Throttle.vue
页面分享组件（设置History路由模式下。页面的分享和微信JS-SDK的签名功能） history_share.js
设置标题组件（设置公众号网页标题） title.js
处理时间（短时间显示，时间戳转换）time.js

其他

Vue中，应尽量少的使用变量，如果变量比较多，可以合并后使用对象或组合。
不涉及双向绑定的变量，应放到data外部，提升性能。例如：

  <template v-if="backTop">
    <div class="back-top" @click.prevent="goTop">
      <i class="el-icon-caret-top"></i>
    </div>
  </template>

  <script>
    let localCartData = {}; //不涉及dom渲染，只涉及变量临时存储。
    export default {
      name: "AppMain",
      data() {
        return {
          backTop: false,
          form: {
            name: "", 
            phone: ""
          }
        }
      }
    }
  </script>

7. 代码注释规范

注释格式

JS中统一使用 /**/ 或者 // 来进行注释。
JS、HTML 和 CSS规范如下：

HTML注释
for循环体循环层，需要加注释

  <!-- user-header begin -->

  <!-- user-header end -->

JS 注释

CSS 注释

使用JSDoc
JSDoc的文档

生成JSDoc的快捷操作是敲 /** 回车 */

快捷方式输入后

@description
使用@description可以在代码提示时显示被描述变量或者函数的描述信息。
例子：


/**  
 * @description 这是一个构造函数  
 */  
function Animal(name,weight){  
    this.name = name;  
    this.weight = weight;  
}

效果：

使用效果

@example
使用@example可以提示代码示例。
例子:

 /**
 * @description 这是一个构造函数  
 * @example   
 * var animal = new Animal('恐龙',1000);  
 * @constructor  
 */  
function Animal(name,weight){  
    this.name = name;  
    this.weight = weight;  
}

效果：