開發規範

本文檔為前端 vue 開發規範(包含規範目的,命名規範,結構化規範,註釋規範,編碼規範,CSS 規範)

規範目的

為提高團隊協作效率，便於後台人員添加功能及前端後期優化維護，輸出高質量的文檔

命名規範

為了讓大家書寫可維護的代碼，而不是一次性的代碼，讓團隊當中其他人看你的代碼能一目瞭然，甚至一段時間時候後你再看你某個時候寫的代碼也能看

普通變量命名規範

• 命名方法 ：駝峯命名法

• 命名規範 ：

  1. 命名必須是跟需求的內容相關的詞，比如説我想申明一個變量，用來表示我的學校，那麼我們可以這樣定義const mySchool = "我的學校";
  2. 命名是複數的時候需要加s,比如説我想申明一個數組，表示很多人的名字，那麼我們可以這樣定義const names = new Array();

常量命名規範

• 命名方法 : 全部大寫
• 命名規範 : 使用大寫字母和下劃線來組合命名，下劃線用以分割單詞。

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

組件命名規範

官方文檔推薦及使用遵循規則：

PascalCase (單詞首字母大寫命名)是最通用的聲明約定

kebab-case (短橫線分隔命名) 是最通用的使用約定

• 組件名應該始終是多個單詞的，根組件 App 除外
• 有意義的名詞、簡短、具有可讀性

• 使用遵循 kebab-case 約定

  • 在頁面中使用組件需要前後閉合，並以短線分隔，如（<abcd-date-picker></abcd-date-picker>，<abcd-table></abcd-table>）
• 導入及註冊組件時，遵循 PascalCase 約定
• 同時還需要注意：必須符合自定義元素規範: 切勿使用保留字。

method 方法命名命名規範

• 駝峯式命名，統一使用動詞或者動詞+名詞形式

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

• init、refresh 單詞除外
• 儘量使用常用單詞開頭（set、get、go、change、has）

page 下的文件命名

• 只有一個文件的情況下不會出現文件夾，而是直接放在 page 目錄下面，如 index.vue
• 儘量是名詞,且使用駝峯命名法
• 文件夾命名儘量語義化（maintenancManage、maintenancPlanApply）
• 名字至少兩個單詞（good: workbenchIndex）（bad:workbench）

props 命名

在聲明 prop 的時候，其命名應該始終使用 camelCase，而在模板中應該始終使用 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>

結構化規範

vue 文件基本結構

 <template>
    <div>
      <!--必須在div中編寫頁面-->
    </div>
 </template>
  <script>
   export default {
    components : {
       },
       data () {
         return {
         }
       },
       mounted() {
      }，
       methods: {
       }
    }
   </script>
   <!--聲明語言，並且添加scoped-->
   <style lang="scss" scoped>
   </style>

多個特性的元素規範

多個特性的元素應該分多行撰寫，每個特性一行。(增強更易讀)

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

元素特性的順序

原生屬性放前面，指令放後面

如下所示：

  - class
  - id,ref
  - name
  - data-*
  - src, for, type, href,value,max-length,max,min,pattern
  - title, alt，placeholder
  - is
  - v-for
  - key
  - v-if
  - v-else
  - v-show
  - v-model
  - v-bind,:
  - v-on,@
  - v-html

組件選項順序

如下所示：

- components
  - props
  - data
  - computed
  - created
  - mounted
  - metods
  - filter
  - watch

註釋規範

代碼註釋在一個項目的後期維護中顯的尤為重要，所以我們要為每一個被複用的組件編寫組件使用説明，為組件中每一個方法編寫方法説明

務必添加註釋列表

1. 公共組件使用説明
2. 各組件中重要函數或者類説明
3. 複雜的業務邏輯處理説明
4. 特殊情況的代碼處理説明,對於代碼中特殊用途的變量、存在臨界值、函數中使用的 hack、使用了某種算法或思路等需要進行註釋描述
5. 多重 if 判斷語句
6. 單行註釋使用//

編碼規範

優秀的項目源碼，即使是多人開發，看代碼也如出一人之手。統一的編碼規範，可使代碼更易於閲讀，易於理解，易於維護。儘量按照 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'

• 如果模塊默認輸出一個函數，函數名的首字母應該小寫。

 function makeStyleGuide() {
  }
 
  export default makeStyleGuide;

• 如果模塊默認輸出一個對象，對象名的首字母應該大寫

const StyleGuide = {
    es6: {
    }
  };
 
  export default StyleGuide;

指令規範

(1) 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>

(2) 避免 v-if 和 v-for 同時用在一個元素上（性能問題）

　　以下為兩種解決方案：

• 將數據替換為一個計算屬性，讓其返回過濾後的列表

<!-- 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>

• 將 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 使用完及時刪除！！！

CSS 規範

通用規範

(1) 統一使用"-"連字符

(2) 省略值為 0 時的單位

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

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

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

(4) 建議並適當縮寫值，提高可讀性，特殊情況除外

​ “建議並適當”是因為縮寫總是會包含一系列的值，而有時候我們並不希望設置某一值，反而造成了麻煩，那麼這時候你可以不縮寫，而是分開寫。

​ 當然，在一切可以縮寫的情況下，請務必縮寫，它最大的好處就是節省了字節，便於維護，並使閲讀更加一目瞭然。

(5) 當使用 Sass 的嵌套功能的時候，重要的是有一個明確的嵌套順序，以下內容是一個 SCSS 塊應具有的順序。

• 當前選擇器的樣式屬性
• 父級選擇器的偽類選擇器 (:first-letter, :hover, :active etc)
• 偽類元素 (:before and :after)
• 父級選擇器的聲明樣式 (.selected, .active, .enlarged etc.)
• 用 Sass 的上下文媒體查詢
• 子選擇器作為最後的部分

.product-teaser {
    // 1. Style attributes
    display: inline-block;
    padding: 1rem;
    background-color: whitesmoke;
    color: grey;

    // 2. Pseudo selectors with parent selector
    &:hover {
      color: black;
    }

    // 3. Pseudo elements with parent selector
    &:before {
      content: "";
      display: block;
      border-top: 1px solid grey;
    }

    &:after {
      content: "";
      display: block;
      border-top: 1px solid grey;
    }

    // 4. State classes with parent selector
    &.active {
      background-color: pink;
      color: red;

      // 4.2. Pseuso selector in state class selector
      &:hover {
        color: darkred;
      }
    }

    // 5. Contextual media queries
    @media screen and (max-width: 640px) {
      display: block;
      font-size: 2em;
    }

    // 6. Sub selectors
    > .content > .title {
      font-size: 1.2em;

      // 6.5. Contextual media queries in sub selector
      @media screen and (max-width: 640px) {
        letter-spacing: 0.2em;
        text-transform: uppercase;
      }
    }
  }

特殊規範

• 對用頁面級組件樣式，應該是有作用域的
• 對於公用組件或者全局組件庫，我們應該更傾向於選用基於 class 的 BEM 策略

BEM定義
Block Element Modifier的首字母縮寫，是一種css的命名規範，一般寫作.block__element--modifier

B(block)：獨立的頁面及邏輯單元。 b-name

E(element): 塊中的組成部分，不能脱離存在，一般為元素的功能單詞或元素的標籤。__element

M(modifier): 修飾符，一般為某個元素的樣式或處於的一種狀態。--modifier

<style lang='scss'></style> // bad

  <!-- 使用 scoped 作用域 -->
  <style lang='scss' scoped></style> // good

  <!-- 使用 BEM 約定 -->
  <style> // good
  .c-Button {
    border: none;
    border-radius: 2px;
  }

  .c-Button--close {
    background-color: red;
  }
  </style>

開發模式token調用後台服務

開發環境需要在request.js文件中給表頭添加的token

網絡請求

當整個框架搭建完畢以後，前端程序員最主要的工作就是發起請求，渲染數據。現在我們就來完整地走一遍這個過程。

配置代理

打開根目錄下的vue.config.js文件

配置攔截器

打開src/utils/request.js，此文件封裝了一個axios請求對象，該系統中的網絡請求都是基於這個對象來處理的。

可以在網絡請求發送之前添加服務器==請求攔截==，在開發環境通常需要模擬添加請求頭用户token信息

service.interceptors.request.use(
    config => {
        if (config.url.indexOf('oauth')<0) {
            config.url='/api/'+config.url;
        }
        config.headers.common.Authorization ='Bearer'+sessionStorage.getItem('access_token'); 
        return config;
    },
    error => {
        return Promise.reject();
    }
);

可以在網絡請求發送之前和收到服務端回覆之後進行==響應攔截==。比如根據服務端的狀態碼判斷請求是否正常，若不正常給出相應的提示。若狀態碼不一致可直接返回請求數據

service.interceptors.response.use(
    response => {
        let resData = response.data;
        if (response.status === 200) {
            if (resData.code === 'CODE_4008') {
                Message.closeAll();
                Message.error('登錄過期，請重新登錄');
                sessionStorage.removeItem('access_token');
                sessionStorage.removeItem('userInfo');
                sessionStorage.removeItem('teamInfo');
                localStorage.removeItem('MENUSMODEL');
                window.location.href = "/#/login";
            } else {
                return resData;
            }
        } else {
            Promise.reject();
        }
    },
    error => {
        Message.error(error.response.data.msg);
        return Promise.reject();
    },
);

掛載請求對象

在src/api下的js文件中導入網絡請求對象直接使用

import request from '@/utils/request'

接口描述

公共接口

獲取當前用户信息

用户信息存儲在SessionStorgae中，需要的話可以自行獲取

（1）接口簡要描述

​ 查詢行政區劃樹

（2）請求URL

cbb-userauth/adcd/v2/queryAdTree

（3）請求方式

• GET

（4）返回示例

（5）返回參數説明

菜單權限控制以及動態菜單

根據用户id以及所要登錄系統的userName來獲取該登錄人員所對應的權限菜單列表，然後通過工具函數來生成路由菜單，並存儲在vuex供左側菜單使用對應圖8

（1）接口簡要描述

獲取權限菜單

（2）請求URL

cbb-smart-drain-backend/permission/getFunInfoByUserNameAndPid

（3）請求方式

• GET

（4）返回示例

（5）處理菜單數據

（6）動態路由掛載