史上最全的Vue開發規範

蔡俊鋒發表於2019-01-19
Vue

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>


 

相關文章