Vue 開發規範目錄及說明

本文件為前端 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 除外

• 有意義的名詞、簡短、具有可讀性

• 命名遵循 PascalCase 約定

  • 公用元件以 Abcd (公司名縮寫簡稱) 開頭，如（AbcdDatePicker,AbcdTable）

  • 頁面內部元件以元件模組名簡寫為開頭，Item 為結尾，如（StaffBenchToChargeItem，StaffBenchAppNotArrItem）

• 使用遵循 kebab-case 約定

  • 在頁面中使用元件需要前後閉合，並以短線分隔，如（<abcd-date-picker></abcd-date-picker>，<abcd-table></abcd-table>）

• 匯入及註冊元件時，遵循 PascalCase 約定

• 同時還需要注意：必須符合自定義元素規範: 切勿使用保留字。

method 方法命名命名規範

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

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

    // good
  jumpPage、openCarInfoDialog

複製程式碼

• 請求資料方法，以 data 結尾

  //bad
  takeData、confirmData、getList、postForm

  // good
  getListData、postFormData
複製程式碼

• init、refresh 單詞除外

• 儘量使用常用單詞開頭（set、get、go、can、has、is）

附： 函式方法常用的動詞:

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 聚集
複製程式碼

views 下的檔案命名

• 只有一個檔案的情況下不會出現資料夾，而是直接放在 views 目錄下面，如 index.vue

• 儘量是名詞,且使用駝峰命名法

• 開頭的單詞就是所屬模組名字（workbenchIndex、workbenchList、workbenchEdit）

• 名字至少兩個單詞（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>
複製程式碼

例外情況

1. 作用域不大臨時變數可以簡寫，比如：str，num，bol，obj，fun，arr。

2. 迴圈變數可以簡寫，比如：i，j，k 等。

結構化規範

目錄資料夾及子檔案規範

• 以下統一管理處均對應相應模組
• 以下全域性檔案檔案均以 index.js 匯出，並在 main.js 中匯入
• 以下臨時檔案，在使用後，介面已經有了，發版後清除

src                               原始碼目錄
|-- api                              介面，統一管理
|-- assets                           靜態資源，統一管理
|-- components                       公用元件，全域性檔案
|-- filters                          過濾器，全域性工具
|-- icons                            圖示，全域性資源
|-- datas                            模擬資料，臨時存放
|-- lib                              外部引用的外掛存放及修改檔案
|-- mock                             模擬介面，臨時存放
|-- router                           路由，統一管理
|-- store                            vuex, 統一管理
|-- views                         檢視目錄
|   |-- staffWorkbench               檢視模組名
|   |-- |-- staffWorkbench.vue       模組入口頁面
|   |-- |-- indexComponents          模組頁面級元件資料夾
|   |-- |-- components               模組通用元件資料夾
複製程式碼

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
  - 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
複製程式碼

元件選項順序

如下所示：

  - components
  - props
  - data
  - computed
  - created
  - mounted
  - metods
  - filter
  - watch
複製程式碼

註釋規範

程式碼註釋在一個專案的後期維護中顯的尤為重要，所以我們要為每一個被複用的元件編寫元件使用說明，為元件中每一個方法編寫方法說明

務必新增註釋列表

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 呼叫示例
      *  <hbTable :title="title" :columns="columns" :tableData="tableData"></hbTable>
      **/
複製程式碼

編碼規範

優秀的專案原始碼，即使是多人開發，看程式碼也如出一人之手。統一的編碼規範，可使程式碼更易於閱讀，易於理解，易於維護。儘量按照 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'
複製程式碼

1. 解構賦值

• 陣列成員對變數賦值時，優先使用解構賦值

  // 陣列解構賦值
  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 }) {}
複製程式碼

1. 拷貝陣列

   使用擴充套件運算子（...）拷貝陣列。

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

  // bad
  const itemsCopy = items

  // good
  const itemsCopy = [...items]
複製程式碼

1. 箭頭函式

   需要使用函式表示式的場合，儘量用箭頭函式代替。因為這樣更簡潔，而且繫結了 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. 模組

• 如果模組只有一個輸出值，就使用 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. 指令有縮寫一律採用縮寫形式

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

  // good
  :class="{'show-left'：true}"
  @click="getListData"
複製程式碼

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>
複製程式碼

1. 避免 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 使用完及時刪除

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);
複製程式碼

CSS 規範

通用規範

1. 統一使用"-"連字元

2. 省略值為 0 時的單位

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

 // good
  padding-bottom: 0;
  margin: 0;
複製程式碼

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

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

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

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

  // 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. 宣告應該按照下表的順序

左到右，從上到下

顯示屬性	自身屬性	文字屬性和其他修飾
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. 元素選擇器應該避免在 scoped 中出現

   官方文件說明：在 scoped 樣式中，類選擇器比元素選擇器更好，因為大量使用元素選擇器是很慢的。

2. 分類的命名方法

   使用單個字母加上"-"為字首

   佈局（grid）（.g-）；

   模組（module）（.m-）；

   元件（unit）（.u-）；

   功能（function）（.f-）；

   皮膚（skin）（.s-）；

   狀態（.z-）。

3. 統一語義理解和命名

佈局（.g-）

語義	命名	簡寫
文件	doc	doc
頭部	head	hd
主體	body	bd
尾部	foot	ft
主欄	main	mn
主欄子容器	mainc	mnc
側欄	side	sd
側欄子容器	sidec	sdc
盒容器	wrap/box	wrap/box

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

語義	命名	簡寫
導航	nav	nav
子導航	subnav	snav
麵包屑	crumb	crm
選單	menu	menu
選項卡	tab	tab
標題區	head/title	hd/tt
內容區	body/content	bd/ct
列表	list	lst
表格	table	tb
表單	form	fm
熱點	hot	hot
排行	top	top
登入	login	log
標誌	logo	logo
廣告	advertise	ad
搜尋	search	sch
幻燈	slide	sld
提示	tips	tips
幫助	help	help
新聞	news	news
下載	download	dld
註冊	regist	reg
投票	vote	vote
版權	copyright	cprt
結果	result	rst
標題	title	tt
按鈕	button	btn
輸入	input	ipt

功能（.f-）

語義	命名	簡寫
浮動清除	clearboth	cb
向左浮動	floatleft	fl
向右浮動	floatright	fr
內聯塊級	inlineblock	ib
文字居中	textaligncenter	tac
文字居右	textalignright	tar
文字居左	textalignleft	tal
垂直居中	verticalalignmiddle	vam
溢位隱藏	overflowhidden	oh
完全消失	displaynone	dn
字型大小	fontsize	fs
字型粗細	fontweight	fw

皮膚（.s-）

語義	命名	簡寫
字型顏色	fontcolor	fc
背景	background	bg
背景顏色	backgroundcolor	bgc
背景圖片	backgroundimage	bgi
背景定位	backgroundposition	bgp
邊框顏色	bordercolor	bdc

狀態（.z-）

語義	命名	簡寫
選中	selected	sel
當前	current	crt
顯示	show	show
隱藏	hide	hide
開啟	open	open
關閉	close	close
出錯	error	err
不可用	disabled	dis

sass 規範

1. 當使用 Sass 的巢狀功能的時候，重要的是有一個明確的巢狀順序，以下內容是一個 SCSS 塊應具有的順序。

   1. 當前選擇器的樣式屬性
   2. 父級選擇器的偽類選擇器 (:first-letter, :hover, :active etc)
   3. 偽類元素 (:before and :after)
   4. 父級選擇器的宣告樣式 (.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;
      }
    }
  }
複製程式碼

特殊規範

• 對用頁面級元件樣式，應該是有作用域的
• 對於公用元件或者全域性元件庫，我們應該更傾向於選用基於 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>