前端编码规范 ​

一、命名规范 ​

代码中的命名需语义化，优先使用英文命名，实在想不到可用拼音全拼命名。严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。注意，即使纯拼音命名方式也要避免采用。

常见的命名规则有以下几种：

1. 小写字母+中划线，例如：boor-admin
2. 小写字母+下划线，例如：node_modules
3. 小驼峰命名，例如：boorAdmin
4. 大驼峰命名，例如：BoorAdmin
5. 常量命名，例如：BASE_URL

项目命名 ​

全部采用小写字母+中划线命名。例如：

boor-admin 、 boor-micro-frontends 等。

目录命名 ​

同项目命名。

文件命名 ​

同项目命名，例如：

# good
render-dom.js
news-info.html
company-logo-dark.png
# bad
RenderDom.js
xwxq.html
gslogo.png

代码命名 ​

class命名 ​

全部采用小写字母+中划线命名，例如：

<!-- good -->
<img class="company-logo" src="xxx" alt="xxx" />
<!-- bad -->
<img class="companyLogo" src="xxx" alt="xxx" />

scss命名 ​

scss中的变量、函数、混入等等采用小驼峰命名,例如：

// 变量
$mainContainerWidth: 1200px;
// 函数
@function columnWidth($col, $total) {
  @return percentage($col/$total);
}
// 混入
@mixin redBox {
  width: 50px;
  height: 50px;
  background: red;
}
.box {
  @include redBox;
}

JS命名 ​

// 变量使用小驼峰命名
let pageSize = 10
// 常量使用全大写+下划线命名
const BASE_URL = 'http://xxxx'
// 普通函数使用小驼峰命名
const getAppData = () => {}
// 构造函数、class类使用大驼峰命名，一个单词时首字母大写
class Person {}

/* 如果使用ts */
// 接口、枚举、装饰器等使用大驼峰命名，一个单词时首字母大写
interface StepsProps {
  active: number
  label: string
}
enum Color { Red, Green, Blue }
@Component

二、代码规范 ​

公共规范：

1. 代码统一使用2个空格缩进（一个tab），2个空格足以让代码有层次感。
2. 一个文件夹内不要出现没有任何关联的文件。例如：config文件夹只存放配置文件
3. 所有页面禁止出现前端报错，影响页面性能的警告也应该尽量解决。
4. 所有页面传参不允许出现前端自定义字段参数，全部使用后端接口提供的字段，字段名在使用时也应该保持一致，不允许同一个含义的东西写好几个不同字段。

Vue规范 ​

以下模板之类的规范同样适用于html

1. 使用H5语义化标签。

2. 结构、样式、行为分离。禁止图方便在标签上直接通过style写样式。

3. 组件的样式必须加 scoped

4. components根目录下需要创建一个doc.md 文件，每个组件的使用必须都有详细文档。更新组件时也需在文档中备注更新细节。

5. 在vue文件中的style scoped标签下，应当避免使用@import 导入样式,使用@import 导入的样式不受scoped影响，依旧会作用在全局。

6. 组件的封装尽可能地少暴露参数。高内聚的组件使用起来更方便。

7. 使用项目中封装好的组件，达成页面一致性。如果内置组件无法完成需求再尝试修改或增加新组件

8. 组件或标签内无内容的统一改为单标签：

   vue

   <!-- good -->
   <el-input value="xxx" />
   <navBar />
   <!-- bad -->
   <el-input value="xxx"></el-input>
   <navBar></navBar>

   1
   2
   3
   4
   5
   6
   

9. 必须开启eslint，并且保证每次提交没有任何eslint警告

10. 路由命名应该根据页面的文件或文件夹命名。禁止出现相同name的路由。

11. 路由跳转尽可能少携带参数。参数传递只能跨一级页面，多级页面需要后端重新提供参数。

12. 路由必须使用懒加载机制:

    js

    // good
    {
      path: "/home",
      component: () => import('../views/home/index.vue')
    }
    
    // bad
    import Home from '../views/home/index.vue'
    {
      path: "/home",
      component: Home
    }

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    

13. vuex如果做了持久化处理就不要再使用本地存储。统一使用vuex储存信息。

14. 减少不必要的换行，除非真的特别长(接近2屏)。换行越少一眼看到的代码就越多，收集到的信息也越多，提高代码可读性，有逻辑性相关的地方代码过长必须换行(比如if判断之类的)。例如：

    vue

    <!-- bad -->
    <el-table :data="tableData">
      <el-table-column
        prop="date"
        label="日期"
        width="180">
      </el-table-column>
      <el-table-column
        prop="name"
        label="姓名"
        width="180">
      </el-table-column>
      <el-table-column
        prop="address"
        label="地址">
      </el-table-column>
    </el-table>
    
    <!-- good -->
    <el-table :data="tableData">
      <el-table-column prop="date" label="日期" width="180" />
      <el-table-column prop="name" label="姓名" width="180" />
      <el-table-column prop="address" label="地址" />
    </el-table>
    <!-- 原因：假如这个表格有几十列的情况下我们需要修改某一列的信息，第一步肯定是先找到列，再找列当中的属性。第一种写法，整个table组件要占几百行代码，一屏只能看到4-5列的信息，找特定列估计只能用ctrl+F了。而换成第二种一屏起码可以收集到15-20列的信息，更容易找到需要修改的列。 -->

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    

15. 对于复杂的页面，不要把所有东西写在一个.vue文件内，导致一个页面几千行代码。对于这种复杂页面需以一个文件夹作为一个页面，有复用的结构可抽离成组件，例如创建一个home文件夹结构如下：

    sh

    views
    ├───home
    │   ├───components # 只作用在当前页面的组件(可选)
    │   ├───index.vue
    │   ├───index.js
    │   └───config.js # 可选
    └───other.vue

    1
    2
    3
    4
    5
    6
    7
    

    在index.vue 写页面结构与样式,逻辑通过import导入

    vue

    <template>
      ...
    </template>
    <script lang="ts">
    import Home from './'
    export default Home
    </script>
    <style lang="scss" scoped>
    // ...
    </style>

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    

    在config.js中写一些与逻辑无关的配置项，例如表格的表头信息等，避免直接在data中定义，导致几百行的data。

    js

    export const tableHeader = [
      { label: '名称', prop: 'name', align: 'center' },
      // ...
    ]

    1
    2
    3
    4
    

    在index.js 写页面逻辑

    js

    import { tableHeader } from './config'
    export default {
      data(){
        return {
          tableHeader,
          // ...
        }
      },
      methods:{},
      // ...
    }

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    

样式规范 ​

1. 全局样式中禁止使用 !important ，即便是在单独的组件中也应当避免使用 !important ，需要修改样式最好使用选择器提升权重。

2. 尽量使用简写样式，0px时去掉单位，颜色除了透明用rgba其它都用16进制。16进制颜色可简写时就简写

   scss

   // bad
   div {
     padding-top: 5px;
     padding-right: 10px;
     padding-bottom: 0px;
     background-color: #000000;
   }
   
   // good
   div {
     padding: 5px 10px 0 0;
     background-color: #000;
   }

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   

3. 同一个选择器禁止在两个不同地方出现，例如：

   scss

   .wrap{
     width: 100%;
   }
   // 中间省略部分代码...
   .wrap{
     width: auto;
   }

   1
   2
   3
   4
   5
   6
   7
   

4. scss 中同级样式用 & 符代替当前块的元素,例如：

   scss

   // bad
   .box {
     width: 100px;
   }
   .box.red {
     color: red;
   }
   
   // good
   .box {
     width: 100px;
     &.red {
       color: red;
     }
   }

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   

JS规范 ​

1. 字符串尽量使用单引号

2. 使用ES6+ 语法

   js

   /**
    * 使用let代替var,常量使用const
    * 箭头函数只有一个参数的时候省略括号。
    */
   
   // bad
   var num = 0
   function getData(params) {...}
   
   // good
   let num = 0
   const getData = params => {...}

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   

3. console、debuger、alert等不要提交到代码仓库

4. 不要有任何多余的代码。由于需求改变多出的代码，必须在不影响其它功能的情况下将其相关联的属性、方法都得删除，没用的代码日积月累后面就没法维护了。注释的代码如果有用的情况下写好备注为什么存在，并且使用TODO注释。

5. 没用到的参数就别写上去。特别是forEach有时候用不到index索引就没必要写。

6. 使用三元运算符替代简单的if判断，但多重判断的情况一定要优先使用if而不是三目运算符。代码可读性一定比代码简洁性的优先级要高。

7. 主要的逻辑方法和属性都得加注释，注释不要写废话，写明方法是什么作用，需要传什么参数，有什么返回值。

8. 禁止使用 == 与 != 来做任何判断，虽然js提供了这个对类型判断并不严格的语法，但并不建议使用，很多bug都是由各种类型的隐式转换，导致类型不明确出现的。需使用 === 与 !== 代替它们。

9. 不要无意义声明变量，例如：

   js

   // bad
   const request = () => {
     let params = {
       pageSize: 10,
       currentPage: 1
     }
     getData(params)
   }
   
   // good
   const request = () => getData({
     pageSize: 10,
     currentPage: 1
   })

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   

10. 少使用不常用的隐式转换，写代码不是炫技，花里胡哨的代码不是每个人都看得懂

11. 使用async/await替代promise.then语法, 提高代码可读性。

如果使用ts:

1. 不要使用any来声明类型，用any还不如直接写js。
2. 每个方法都得声明参数类型与返回值。没有返回值应该用void而不是any。