Vue.js 開發(fā)規(guī)范目錄及說明

本文檔為前端 vue 開發(fā)規(guī)范

• 規(guī)范目的
• 命名規(guī)范
• 結(jié)構(gòu)化規(guī)范
• 注釋規(guī)范
• 編碼規(guī)范
• CSS 規(guī)范

規(guī)范目的

為提高團(tuán)隊(duì)協(xié)作效率

便于后臺(tái)人員添加功能及前端后期優(yōu)化維護(hù)

輸出高質(zhì)量的代碼及文檔

一、命名規(guī)范

為了讓大家書寫可維護(hù)的代碼，而不是一次性的代碼

讓團(tuán)隊(duì)當(dāng)中其他人看你的代碼能一目了然

普通變量命名規(guī)范

• 命名方法 ：駝峰命名法
• 命名規(guī)范 ：
  1. 命名必須是跟需求的內(nèi)容相關(guān)的詞活箕，比如說我想申明一個(gè)變量缭乘，用來表示我的業(yè)務(wù)，那么我們可以這樣定義const mySchool = "我的業(yè)務(wù)";
  2. 命名是復(fù)數(shù)的時(shí)候需要加s,比如說我想申明一個(gè)數(shù)組植袍，表示很多人的名字，那么我們可以這樣定義const names = new Array();

常量命名

• 命名方法 : 全部大寫
• 命名規(guī)范 : 使用大寫字母和下劃線來組合命名，下劃線用以分割單詞暇番。

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

組件命名規(guī)范

官方文檔推薦及使用遵循規(guī)則：

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

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

• 組件名應(yīng)該始終是多個(gè)單詞的，根組件 App 除外
• 有意義的名詞思喊、簡短壁酬、具有可讀性
• 命名遵循 PascalCase 約定
  • 公用組件以 Abcd (公司名縮寫簡稱) 開頭，如（AbcdDatePicker,AbcdTable）
  • 頁面內(nèi)部組件以組件模塊名簡寫為開頭恨课，Item 為結(jié)尾舆乔，如（StaffBenchToChargeItem，StaffBenchAppNotArrItem）
• 使用遵循 kebab-case 約定
  • 在頁面中使用組件需要前后閉合剂公，并以短線分隔希俩，如（<abcd-date-picker></abcd-date-picker>，<abcd-table></abcd-table>）
• 導(dǎo)入及注冊組件時(shí)纲辽，遵循 PascalCase 約定
• 同時(shí)還需要注意：必須符合自定義元素規(guī)范: 切勿使用保留字颜武。

method 方法命名命名規(guī)范

• 駝峰式命名璃搜，統(tǒng)一使用動(dòng)詞或者動(dòng)詞+名詞形式

//bad
go、nextPage鳞上、show这吻、open、login

// good
jumpPage因块、openCarInfoDialog

• 請求數(shù)據(jù)方法橘原，以 data 結(jié)尾

//bad
takeData、confirmData涡上、getList趾断、postForm

// good
getListData、postFormData

• init吩愧、refresh 單詞除外
• 盡量使用常用單詞開頭（set芋酌、get、go雁佳、can脐帝、has、is）

附： 函數(shù)方法常用的動(dòng)詞:

get 獲取/set 設(shè)置,
add 增加/remove 刪除
create 創(chuàng)建/destory 移除
start 啟動(dòng)/stop 停止
open 打開/close 關(guān)閉,
read 讀取/write 寫入
load 載入/save 保存,
create 創(chuàng)建/destroy 銷毀
begin 開始/end 結(jié)束,
backup 備份/restore 恢復(fù)
import 導(dǎo)入/export 導(dǎo)出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附著/detach 脫離
bind 綁定/separate 分離,
view 查看/browse 瀏覽
edit 編輯/modify 修改,
select 選取/mark 標(biāo)記
copy 復(fù)制/paste 粘貼,
undo 撤銷/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 減少
play 播放/pause 暫停,
launch 啟動(dòng)/run 運(yùn)行
compile 編譯/execute 執(zhí)行,
debug 調(diào)試/trace 跟蹤
observe 觀察/listen 監(jiān)聽,
build 構(gòu)建/publish 發(fā)布
input 輸入/output 輸出,
encode 編碼/decode 解碼
encrypt 加密/decrypt 解密,
compress 壓縮/decompress 解壓縮
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 連接/disconnect 斷開,
send 發(fā)送/receive 接收
download 下載/upload 上傳,
refresh 刷新/synchronize 同步
update 更新/revert 復(fù)原,
lock 鎖定/unlock 解鎖
check out 簽出/check in 簽入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展開/collapse 折疊
begin 起始/end 結(jié)束,
start 開始/finish 完成
enter 進(jìn)入/exit 退出,
abort 放棄/quit 離開
obsolete 廢棄/depreciate 廢舊,
collect 收集/aggregate 聚集

views 下的文件命名

• 只有一個(gè)文件的情況下不會(huì)出現(xiàn)文件夾糖权，而是直接放在 views 目錄下面堵腹，如 index.vue
• 盡量是名詞,且使用駝峰命名法
• 開頭的單詞就是所屬模塊名字（workbenchIndex、workbenchList星澳、workbenchEdit）
• 名字至少兩個(gè)單詞（good: workbenchIndex）（bad:workbench）

props 命名

在聲明 prop 的時(shí)候疚顷，其命名應(yīng)該始終使用 camelCase，而在模板中應(yīng)該始終使用 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>

例外情況

1. 作用域不大臨時(shí)變量可以簡寫禁偎，比如：str腿堤，num，bol如暖，obj笆檀，fun，arr盒至。
2. 循環(huán)變量可以簡寫酗洒，比如：i，j枷遂，k 等樱衷。

二、結(jié)構(gòu)化規(guī)范

目錄文件夾及子文件規(guī)范

• 以下統(tǒng)一管理處均對(duì)應(yīng)相應(yīng)模塊
• 以下全局文件文件均以 index.js 導(dǎo)出登淘，并在 main.js 中導(dǎo)入
• 以下臨時(shí)文件，在使用后封字，接口已經(jīng)有了黔州，發(fā)版后清除

src                               源碼目錄
|-- api                              接口耍鬓，統(tǒng)一管理
|-- assets                           靜態(tài)資源，統(tǒng)一管理
|-- components                       公用組件流妻，全局文件
|-- filters                          過濾器牲蜀，全局工具
|-- icons                            圖標(biāo)，全局資源
|-- datas                            模擬數(shù)據(jù)绅这，臨時(shí)存放
|-- lib                              外部引用的插件存放及修改文件
|-- mock                             模擬接口涣达，臨時(shí)存放
|-- router                           路由，統(tǒng)一管理
|-- store                            vuex, 統(tǒng)一管理
|-- views                            視圖目錄
|   |-- staffWorkbench               視圖模塊名
|   |-- |-- staffWorkbench.vue       模塊入口頁面
|   |-- |-- indexComponents          模塊頁面級(jí)組件文件夾
|   |-- |-- components               模塊通用組件文件夾

vue 文件基本結(jié)構(gòu)

  <template>
    <div>
      <!--必須在div中編寫頁面-->
    </div>
  </template>
  <script>
    export default {
      components : {

      },

      data () {
        return {

        }
      },
      mounted() {

      }证薇，
      methods: {

      }

   }

  </script>

  <!--聲明語言度苔，并且添加scoped-->
  <style lang="less" scoped>

  </style>

多個(gè)特性的元素規(guī)范

多個(gè)特性的元素應(yīng)該分多行撰寫，每個(gè)特性一行浑度。(增強(qiáng)更易讀)

<!-- 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
- aria-*, role
- required,readonly,disabled
- is
- v-for
- key
- v-if
- v-else-if
- v-else
- v-show
- v-cloak
- v-pre
- v-once
- v-model
- v-bind,:
- v-on,@
- v-html
- v-text

組件選項(xiàng)順序

如下所示：

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

三箩张、注釋規(guī)范

代碼注釋在一個(gè)項(xiàng)目的后期維護(hù)中顯的尤為重要甩骏，所以我們要為每一個(gè)被復(fù)用的組件編寫組件使用說明，為組件中每一個(gè)方法編寫方法說明

務(wù)必添加注釋列表

1. 公共組件使用說明
2. 各組件中重要函數(shù)或者類說明
3. 復(fù)雜的業(yè)務(wù)邏輯處理說明
4. 特殊情況的代碼處理說明,對(duì)于代碼中特殊用途的變量先慷、存在臨界值饮笛、函數(shù)中使用的 hack、使用了某種算法或思路等需要進(jìn)行注釋描述
5. 多重 if 判斷語句
6. 注釋塊必須以/**（至少兩個(gè)星號(hào)）開頭**/
7. 單行注釋使用//

單行注釋

注釋單獨(dú)一行论熙，不要在代碼后的同一行內(nèi)加注釋福青。例如：

bad
var name =”abc”; // 姓名    

good
// 姓名
var name = “abc”; 

多行注釋

組件使用說明，和調(diào)用說明

/**
* 組件名稱
* @module 組件存放位置
* @desc 組件描述
* @author 組件作者
* @date 2017年12月05日17:22:43
* @param {Object} [title]    - 參數(shù)說明
* @param {String} [columns] - 參數(shù)說明
* @example 調(diào)用示例
*  <hbTable :title="title" :columns="columns" :tableData="tableData"></hbTable>
**/

四赴肚、編碼規(guī)范

優(yōu)秀的項(xiàng)目源碼素跺，即使是多人開發(fā)，看代碼也如出一人之手誉券。統(tǒng)一的編碼規(guī)范指厌，可使代碼更易于閱讀，易于理解踊跟，易于維護(hù)踩验。盡量按照 ESLint 格式要求編寫代碼

源碼風(fēng)格

使用 ES6 風(fēng)格編碼

1. 定義變量使用 let ,定義常量使用 const
2. 靜態(tài)字符串一律使用單引號(hào)或反引號(hào)，動(dòng)態(tài)字符串使用反引號(hào)

// 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'

1. 解構(gòu)賦值

• 數(shù)組成員對(duì)變量賦值時(shí)商玫，優(yōu)先使用解構(gòu)賦值

// 數(shù)組解構(gòu)賦值
const arr = [1, 2, 3, 4]

// bad

const first = arr[0]
const second = arr[1]

// good

const [first, second] = arr

• 函數(shù)的參數(shù)如果是對(duì)象的成員箕憾，優(yōu)先使用解構(gòu)賦值

// 對(duì)象解構(gòu)賦值

// 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 }) {}

1. 拷貝數(shù)組

   使用擴(kuò)展運(yùn)算符（…）拷貝數(shù)組。

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

// bad
const itemsCopy = items

// good

const itemsCopy = [...items]

1. 箭頭函數(shù)

   需要使用函數(shù)表達(dá)式的場合拳昌，盡量用箭頭函數(shù)代替袭异。因?yàn)檫@樣更簡潔，而且綁定了 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);

1. 模塊

• 如果模塊只有一個(gè)輸出值炬藤，就使用 export default御铃，如果模塊有多個(gè)輸出值碴里，就不使用 export default，export default 與普通的 export 不要同時(shí)使用

// bad

import * as myObject from './importModule'

// good
import myObject from './importModule'

• 如果模塊默認(rèn)輸出一個(gè)函數(shù)上真，函數(shù)名的首字母應(yīng)該小寫咬腋。

function makeStyleGuide() {

}

export default makeStyleGuide;

• 如果模塊默認(rèn)輸出一個(gè)對(duì)象，對(duì)象名的首字母應(yīng)該大寫睡互。

  const StyleGuide = {

    es6: {

    }

  };
  export default StyleGuide;

指令規(guī)范

1. 指令有縮寫一律采用縮寫形式

// bad

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

// good

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

1. v-for 循環(huán)必須加上 key 屬性根竿，在整個(gè) for 循環(huán)中 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>

1. 避免 v-if 和 v-for 同時(shí)用在一個(gè)元素上（性能問題）

   以下為兩種解決方案：

• 將數(shù)據(jù)替換為一個(gè)計(jì)算屬性，讓其返回過濾后的列表

  <!-- 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 移動(dòng)至容器元素上 (比如 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 規(guī)范

Props 定義應(yīng)該盡量詳細(xì)

// bad 這樣做只有開發(fā)原型系統(tǒng)時(shí)可以接受

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. 調(diào)試信息 console.log() debugger 使用完及時(shí)刪除
3. 除了三目運(yùn)算就珠，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 規(guī)范

通用規(guī)范

1. 統(tǒng)一使用"-"連字符
2. 省略值為 0 時(shí)的單位

// bad

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

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

1. 如果 CSS 可以做到，就不要使用 JS

2. 建議并適當(dāng)縮寫值嗓违，提高可讀性九巡，特殊情況除外

   “建議并適當(dāng)”是因?yàn)榭s寫總是會(huì)包含一系列的值，而有時(shí)候我們并不希望設(shè)置某一值蹂季，反而造成了麻煩冕广，那么這時(shí)候你可以不縮寫，而是分開寫偿洁。

   當(dāng)然撒汉，在一切可以縮寫的情況下，請務(wù)必縮寫涕滋，它最大的好處就是節(jié)省了字節(jié)睬辐，便于維護(hù)，并使閱讀更加一目了然宾肺。

  // 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;
  }

1. 聲明應(yīng)該按照下表的順序

左到右溯饵，從上到下

  // 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. 元素選擇器應(yīng)該避免在 scoped 中出現(xiàn)

   在 scoped 樣式中，類選擇器比元素選擇器更好锨用，因?yàn)榇罅渴褂迷剡x擇器是很慢的丰刊。

2. 分類的命名方法

   使用單個(gè)字母加上"-"為前綴

   布局（grid）（.g-）；

   模塊（module）（.m-）增拥；

   元件（unit）（.u-）啄巧；

   功能（function）（.f-）；

   皮膚（skin）（.s-）掌栅；

   狀態(tài)（.z-）秩仆。

3. 統(tǒng)一語義理解和命名

布局（.g-）

模塊（.m-）、元件（.u-）

功能（.f-）

皮膚（.s-）

狀態(tài)（.z-）

less 規(guī)范

1. 當(dāng)使用 Less 的嵌套功能的時(shí)候猾封，重要的是有一個(gè)明確的嵌套順序澄耍，以下內(nèi)容是一個(gè) Less 塊應(yīng)具有的順序。
   1. 當(dāng)前選擇器的樣式屬性
   2. 父級(jí)選擇器的偽類選擇器 (:first-letter, :hover, :active etc)
   3. 偽類元素 (:before and :after)
   4. 父級(jí)選擇器的聲明樣式 (.selected, .active, .enlarged etc.)
   5. 用 Sass 的上下文媒體查詢
   6. 子選擇器作為最后的部分

  .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;
      }
    }
  }

特殊規(guī)范

• 對(duì)用頁面級(jí)組件樣式齐莲，應(yīng)該是有作用域的
• 對(duì)于公用組件或者全局組件庫卿城，我們應(yīng)該更傾向于選用基于 class 的 BEM 策略

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

原文：https://blog.csdn.net/qq_42306435/article/details/104423442