vue項目編碼規範

本文檔摘自Vue官方的編碼規範，結合實際項目給出如下規範建議

1、元件名為多個單詞

元件名應該始終是多個單詞的，根元件

App

除外。

這樣做可以避免跟現有的以及未來的 HTML 元素相沖突，因為所有的 HTML 元素名稱都是單個單詞的。

反例

Vue.component('todo', {
  // ...
}) 
export default {
  name: 'Todo',
  // ...
}

好例子

Vue.component('todo-item', {
  // ...
})
export default {
  name: 'TodoItem',
  // ...
}

2、元件資料

元件的

data

必須是一個函數。

當在元件中使用

data

屬性的時候 (除了

new Vue

外的任何地方)，它的值必須是傳回一個對象的函數。

反例

Vue.component('some-comp', {
  data: {
    foo: 'bar'
  }
})
export default {
  data: {
    foo: 'bar'
  }
}

好例子

Vue.component('some-comp', {
  data: function () {
    return {
      foo: 'bar'
    }
  }
})
export default {
  data () {
    return {
      foo: 'bar'
    }
  }
}

3、Prop 定義

Prop 定義應該盡量詳細。

在你送出的代碼中，prop 的定義應該盡量詳細，至少需要指定其類型。

細緻的prop 定義有兩個好處：

（1）它們寫明了元件的 API，是以很容易看懂元件的用法；

（2）在開發環境下，如果向一個元件提供格式不正确的 prop，Vue 将會告警，以幫助你捕獲潛在的錯誤來源。

反例

// 這樣做隻有開發原型系統時可以接受
props: ['status']

好例子

props: {
      status: {
        type: String,
        required: true,
        validator: function (value) {
          return [
            'syncing',
            'synced',
            'version-conflict',
            'error'
          ].indexOf(value) !== -1
        }
      }
    }

4、為 `v-for` 設定鍵值

總是用

key

配合

v-for

。

在元件上總是用

key

配合

v-for

，以便維護内部元件及其子樹的狀态。

反例

<ul>
  <li v-for="todo in todos">
    {{ todo.text }}
  </li>
</ul>

好例子

<ul>
  <li
    v-for="todo in todos"
    :key="todo.id"
  >
    {{ todo.text }}
  </li>
</ul>

5、避免 `v-if` 和 `v-for` 用在一起

永遠不要把

v-if

和

v-for

同時用在同一個元素上。

6、為元件樣式設定作用域

對于應用來說，頂級

App

元件和布局元件中的樣式可以是全局的，但是其它所有元件都應該是有作用域的。

對于元件庫，我們應該更傾向于選用基于 class 的政策而不是

scoped

特性。

使用唯一的 class 名可以幫你確定那些三方庫的 CSS 不會運用在你自己的 HTML 上。

7、私有屬性名

在插件、混入等擴充中始終為自定義的私有屬性使用

$_

字首。并附帶一個命名空間以回避和其它作者的沖突 (比如

$_yourPluginName_

)。

反例

var myGreatMixin = {
  // ...
  methods: {
    update: function () {
      // ...
    }
  }
}

好例子

var myGreatMixin = {
  // ...
  methods: {
    $_myGreatMixin_update: function () {
      // ...
    }
  }
}

8、元件檔案

隻要有能夠拼接檔案的建構系統，就把每個元件單獨分成檔案。

當你需要編輯一個元件或查閱一個元件的用法時，可以更快速的找到它。

反例

Vue.component('TodoList', {
  // ...
})
Vue.component('TodoItem', {
  // ...
})

好例子

components/
|- TodoList.js
|- TodoItem.js
components/
|- TodoList.vue
|- TodoItem.vue

9、單檔案元件檔案的大小寫

單檔案元件的檔案名應該要麼始終是單詞大寫開頭 (PascalCase)，要麼始終是橫線連接配接 (kebab-case)。

反例

components/
|- mycomponent.vue
components/
|- myComponent.vue

好例子

components/
|- MyComponent.vue
components/
|- my-component.vue

10、基礎元件名

應用特定樣式和約定的基礎元件 (也就是展示類的、無邏輯的或無狀态的元件) 應該全部以一個特定的字首開頭，比如

Base

、

App

或

。

11、單例元件名

隻應該擁有單個活躍執行個體的元件應該以

The

字首命名，以示其唯一性。

這不意味着元件隻可用于一個單頁面，而是每個頁面隻使用一次。這些元件永遠不接受任何 prop，因為它們是為你的應用定制的，而不是它們在你的應用中的上下文。如果你發現有必要添加 prop，那就表明這實際上是一個可複用的元件，隻是目前在每個頁面裡隻使用一次。

12、緊密耦合的元件名

和父元件緊密耦合的子元件應該以父元件名作為字首命名。

如果一個元件隻在某個父元件的場景下有意義，這層關系應該展現在其名字上。因為編輯器通常會按字母順序組織檔案，是以這樣做可以把相關聯的檔案排在一起。

反例

components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue

好例子

components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

13、元件名中的單詞順序

元件名應該以進階别的 (通常是一般化描述的) 單詞開頭，以描述性的修飾詞結尾。

反例

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

好例子

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

14、自閉合元件

在單檔案元件、字元串模闆和JSX中沒有内容的元件應該是自閉合的，但在 DOM 模闆裡永遠不要這樣做。

HTML 并不支援自閉合的自定義元素

反例

<!-- 在單檔案元件、字元串模闆和 JSX 中 -->
<MyComponent></MyComponent>
<!-- 在 DOM 模闆中 -->
<my-component/>

好例子

<!-- 在單檔案元件、字元串模闆和 JSX 中 -->
<MyComponent/>
<!-- 在 DOM 模闆中 -->
<my-component></my-component>

15、模闆中的元件名大小寫

對于絕大多數項目來說，在單檔案元件和字元串模闆中元件名應該總是 PascalCase 的，但是在 DOM 模闆中總是 kebab-case 的。

16、JS/JSX 中的元件名大小寫

JS/[JSX中的元件名應該始終是 PascalCase 的，盡管在較為簡單的應用中隻使用

Vue.component

進行全局元件注冊時，可以使用 kebab-case 字元串。

對于隻通過

Vue.component

定義全局元件的應用來說，我們推薦 kebab-case

17、完整單詞的元件名

元件名應該傾向于完整單詞而不是縮寫。

編輯器中的自動補全已經讓書寫長命名的代價非常之低了，而其帶來的明确性卻是非常寶貴的。不常用的縮寫尤其應該避免。

18、Prop 名大小寫

在聲明 prop 的時候，其命名應該始終使用 camelCase，而在模闆和JSX中應該始終使用 kebab-case。

我們單純的遵循每個語言的約定。在 JavaScript 中更自然的是 camelCase。而在 HTML 中則是 kebab-case。

19、多個特性的元素

多個特性的元素應該分多行撰寫，每個特性一行。

反例

<MyComponent foo="a" bar="b" baz="c"/>

好例子

<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

20、模闆中簡單的表達式

元件模闆應該隻包含簡單的表達式，複雜的表達式則應該重構為計算屬性或方法。

21、簡單的計算屬性

應該把複雜計算屬性分割為盡可能多的更簡單的屬性。

22、帶引号的特性值

非空 HTML 特性值應該始終帶引号 (單引号或雙引号，選你 JS 裡不用的那個)。

在 HTML 中不帶空格的特性值是可以沒有引号的，但這鼓勵了大家在特征值裡不寫空格，導緻可讀性變差。

23、指令縮寫

指令縮寫 (用

表示

v-bind:

和用

表示

v-on:

) 應該要麼都用要麼都不用。

24、元件/執行個體的選項的順序

元件/執行個體的選項應該有統一的順序。

這是我們推薦的元件選項預設順序。它們被劃分為幾大類，是以你也能知道從插件裡添加的新屬性應該放到哪裡。

副作用 (觸發元件外的影響)

el

全局感覺(要求元件以外的知識)

name
parent

元件類型 (更改元件的類型)

functional

模闆修改器 (改變模闆的編譯方式)

delimiters
comments

模闆依賴 (模闆内使用的資源)

components
directives
filters

組合 (向選項裡合并屬性)

extends
mixins

接口 (元件的接口)

inheritAttrs
model
props / propsData

本地狀态 (本地的響應式屬性)

data
computed

事件(通過響應式事件觸發的回調)

watch
生命周期鈎子 (按照它們被調用的順序)

beforeCreate
created
beforeMount
mounted
beforeUpdate
updated
activated
deactivated
beforeDestroy
destroyed

非響應式的屬性 (不依賴響應系統的執行個體屬性)

methods

渲染 (元件輸出的聲明式描述)

template / render
renderError

25、元素特性的順序

元素 (包括元件) 的特性應該有統一的順序。

這是我們為元件選項推薦的預設順序。它們被劃分為幾大類，是以你也能知道新添加的自定義特性和指令應該放到哪裡。

定義 (提供元件的選項)

is

清單渲染 (建立多個變化的相同元素)

v-for

條件渲染 (元素是否渲染/顯示)

v-if
v-else-if
v-else
v-show
v-cloak

渲染方式 (改變元素的渲染方式)

v-pre
v-once

全局感覺 (需要超越元件的知識)

id

唯一的特性 (需要唯一值的特性)

ref
key
slot

雙向綁定 (把綁定和事件結合起來)

v-model

其它特性(所有普通的綁定或未綁定的特性)
事件(元件事件監聽器)

v-on

内容 (覆寫元素的内容)

v-html
v-text

26、元件/執行個體選項中的空行

你可能想在多個屬性之間增加一個空行，特别是在這些選項一屏放不下，需要滾動才能都看到的時候。

當你的元件開始覺得密集或難以閱讀時，在多個屬性之間添加空行可以讓其變得容易。在一些諸如 Vim 的編輯器裡，這樣格式化後的選項還能通過鍵盤被快速導航。

好例子

props: {
  value: {
    type: String,
    required: true
  },

  focused: {
    type: Boolean,
    default: false
  },

  label: String,
  icon: String
},

computed: {
  formattedValue: function () {
    // ...
  },

  inputClasses: function () {
    // ...
  }
}

27、單檔案元件的頂級元素的順序

單檔案元件應該總是讓

<script>

、

<template>

和

<style>

标簽的順序保持一緻。且

<style>

要放在最後，因為另外兩個标簽至少要有一個。

28、沒有在 `v-if` / `v-else-if` / `v-else` 中使用 `key`

如果一組

v-if

v-else

的元素類型相同，最好使用

key

(比如兩個

<div>

元素)。

預設情況下，Vue 會盡可能高效的更新 DOM。這意味着其在相同類型的元素之間切換時，會修補已存在的元素，而不是将舊的元素移除然後在同一位置添加一個新元素。如果本不相同的元素被識别為相同，則會出現意料之外的副作用。

反例

<div v-if="error">
  錯誤：{{ error }}
</div>
<div v-else>
  {{ results }}
</div>

好例子

<div
  v-if="error"
  key="search-status"
>
  錯誤：{{ error }}
</div>
<div
  v-else
  key="search-results"
>
  {{ results }}
</div>

29、 `scoped` 中的元素選擇器

元素選擇器應該避免在

scoped

中出現。

在

scoped

樣式中，類選擇器比元素選擇器更好，因為大量使用元素選擇器是很慢的。

反例

<template>
  <button>X</button>
</template>
<style scoped>button {
  background-color: red;
}</style>

好例子

<template>
  <button class="btn btn-close">X</button>
</template>
<style scoped>.btn-close {
  background-color: red;
}</style>