史上最全 Vue 前端代碼風(fēng)格指南

一、命名規(guī)范

市面上常用的命名規(guī)范：

• camelCase（小駝峰式命名法?—— 首字母小寫）
• PascalCase（大駝峰式命名法 —— 首字母大寫）
• kebab-case（短橫線連接式）
• Snake（下劃線連接式）

1.1 項(xiàng)目文件命名

1.1.1 項(xiàng)目名

全部采用小寫方式， 以短橫線分隔。例：my-project-name。

1.1.2 目錄名

參照項(xiàng)目命名規(guī)則，有復(fù)數(shù)結(jié)構(gòu)時(shí)，要采用復(fù)數(shù)命名法。例：docs、assets、components、directives、mixins、utils、views。

my-project-name/
|-?BuildScript????//?流水線部署文件目錄
|-?docs???????????//?項(xiàng)目的細(xì)化文檔目錄（可選）
|-?nginx??????????//?部署在容器上前端項(xiàng)目?nginx?代理文件目錄
|-?node_modules???//?下載的依賴包
|-?public?????????//?靜態(tài)頁面目錄
????|-?index.html?//?項(xiàng)目入口
|-?src????????????//?源碼目錄
????|-?api????????//?http?請(qǐng)求目錄
????|-?assets?????//?靜態(tài)資源目錄，這里的資源會(huì)被wabpack構(gòu)建
????????|-?icon???//?icon?存放目錄
????????|-?img????//?圖片存放目錄
????????|-?js?????//?公共?js?文件目錄
????????|-?scss???//?公共樣式?scss?存放目錄
????????????|-?frame.scss???//?入口文件
????????????|-?global.scss??//?公共樣式
????????????|-?reset.scss???//?重置樣式
????|-?components?????//?組件
????|-?plugins????????//?插件
????|-?router?????????//?路由
????|-?routes?????????//?詳細(xì)的路由拆分目錄（可選）
????????|-?index.js
????|-?store??????????//?全局狀態(tài)管理
????|-?utils??????????//?工具存放目錄
????????|-?request.js?//?公共請(qǐng)求工具
????|-?views??????????//?頁面存放目錄
????|-?App.vue????????//?根組件
????|-?main.js????????//?入口文件
????|-?tests??????????//?測(cè)試用例
????|-?.browserslistrc//?瀏覽器兼容配置文件
????|-?.editorconfig??//?編輯器配置文件
????|-?.eslintignore??//?eslint?忽略規(guī)則
????|-?.eslintrc.js???//?eslint?規(guī)則
????|-?.gitignore?????//?git?忽略規(guī)則
????|-?babel.config.js?//?babel?規(guī)則
????|-?Dockerfile?//?Docker?部署文件
????|-?jest.config.js
????|-?package-lock.json
????|-?package.json?//?依賴
????|-?README.md?//?項(xiàng)目?README
????|-?vue.config.js?//?webpack?配置
復(fù)制代碼

1.1.3 圖像文件名

全部采用小寫方式， 優(yōu)先選擇單個(gè)單詞命名，多個(gè)單詞命名以下劃線分隔。

banner_sina.gif
menu_aboutus.gif
menutitle_news.gif
logo_police.gif
logo_national.gif
pic_people.jpg
pic_TV.jpg
復(fù)制代碼

1.1.4 HTML 文件名

全部采用小寫方式， 優(yōu)先選擇單個(gè)單詞命名，多個(gè)單詞命名以下劃線分隔。

|-?error_report.html
|-?success_report.html
復(fù)制代碼

1.1.5 CSS 文件名

全部采用小寫方式， 優(yōu)先選擇單個(gè)單詞命名，多個(gè)單詞命名以短橫線分隔。

|-?normalize.less
|-?base.less
|-?date-picker.scss
|-?input-number.scss
復(fù)制代碼

1.1.6 JavaScript 文件名

全部采用小寫方式， 優(yōu)先選擇單個(gè)單詞命名，多個(gè)單詞命名以短橫線分隔。

|-?index.js
|-?plugin.js
|-?util.js
|-?date-util.js
|-?account-model.js
|-?collapse-transition.js
復(fù)制代碼

上述規(guī)則可以快速記憶為“靜態(tài)文件下劃線，編譯文件短橫線”。

1.2 Vue 組件命名

1.2.1 單文件組件名

文件擴(kuò)展名為?.vue?的?single-file components?(單文件組件)。單文件組件名應(yīng)該始終是單詞大寫開頭?(PascalCase)。

components/
|-?MyComponent.vue
復(fù)制代碼

1.2.2 單例組件名

只擁有單個(gè)活躍實(shí)例的組件應(yīng)該以?The?前綴命名，以示其唯一性。

這不意味著組件只可用于一個(gè)單頁面，而是_每個(gè)頁面_只使用一次。這些組件永遠(yuǎn)不接受任何 prop，因?yàn)樗鼈兪菫槟愕膽?yīng)用定制的。如果你發(fā)現(xiàn)有必要添加 prop，那就表明這實(shí)際上是一個(gè)可復(fù)用的組件，_只是目前_在每個(gè)頁面里只使用一次。

比如，頭部和側(cè)邊欄組件幾乎在每個(gè)頁面都會(huì)使用，不接受 prop，該組件是專門為該應(yīng)用所定制的。

components/
|-?TheHeading.vue
|-?TheSidebar.vue
復(fù)制代碼

1.2.3 基礎(chǔ)組件名

基礎(chǔ)組件：不包含業(yè)務(wù)，獨(dú)立、具體功能的基礎(chǔ)組件，比如日期選擇器、模態(tài)框等。這類組件作為項(xiàng)目的基礎(chǔ)控件，會(huì)被大量使用，因此組件的 API 進(jìn)行過高強(qiáng)度的抽象，可以通過不同配置實(shí)現(xiàn)不同的功能。

應(yīng)用特定樣式和約定的基礎(chǔ)組件(也就是展示類的、無邏輯的或無狀態(tài)、不摻雜業(yè)務(wù)邏輯的組件) 應(yīng)該全部以一個(gè)特定的前綴開頭 —— Base。基礎(chǔ)組件在一個(gè)頁面內(nèi)可使用多次，在不同頁面內(nèi)也可復(fù)用，是高可復(fù)用組件。

components/
|-?BaseButton.vue
|-?BaseTable.vue
|-?BaseIcon.vue
復(fù)制代碼

1.2.4 業(yè)務(wù)組件

業(yè)務(wù)組件：它不像基礎(chǔ)組件只包含某個(gè)功能，而是在業(yè)務(wù)中被多個(gè)頁面復(fù)用的（具有可復(fù)用性），它與基礎(chǔ)組件的區(qū)別是，業(yè)務(wù)組件只在當(dāng)前項(xiàng)目中會(huì)用到，不具有通用性，而且會(huì)包含一些業(yè)務(wù)，比如數(shù)據(jù)請(qǐng)求；而基礎(chǔ)組件不含業(yè)務(wù)，在任何項(xiàng)目中都可以使用，功能單一，比如一個(gè)具有數(shù)據(jù)校驗(yàn)功能的輸入框。

摻雜了復(fù)雜業(yè)務(wù)的組件（擁有自身?data、prop?的相關(guān)處理）即業(yè)務(wù)組件應(yīng)該以?Custom?前綴命名。業(yè)務(wù)組件在一個(gè)頁面內(nèi)比如：某個(gè)頁面內(nèi)有一個(gè)卡片列表，而樣式和邏輯跟業(yè)務(wù)緊密相關(guān)的卡片就是業(yè)務(wù)組件。

components/
|-?CustomCard.vue
復(fù)制代碼

1.2.5 緊密耦合的組件名

和父組件緊密耦合的子組件應(yīng)該以父組件名作為前綴命名。?因?yàn)榫庉嬈魍ǔ?huì)按字母順序組織文件，所以這樣做可以把相關(guān)聯(lián)的文件排在一起。

components/
|-?TodoList.vue
|-?TodoListItem.vue
|-?TodoListItemButton.vue
復(fù)制代碼

1.2.6 組件名中單詞順序

組件名應(yīng)該以高級(jí)別的 (通常是一般化描述的) 單詞開頭，以描述性的修飾詞結(jié)尾。?因?yàn)榫庉嬈魍ǔ?huì)按字母順序組織文件，所以現(xiàn)在組件之間的重要關(guān)系一目了然。如下組件主要是用于搜索和設(shè)置功能。

components/
|-?SearchButtonClear.vue
|-?SearchButtonRun.vue
|-?SearchInputQuery.vue
|-?SearchInputExcludeGlob.vue
|-?SettingsCheckboxTerms.vue
|-?SettingsCheckboxLaunchOnStartup.vue
復(fù)制代碼

還有另一種多級(jí)目錄的方式，把所有的搜索組件放到“search”目錄，把所有的設(shè)置組件放到“settings”目錄。我們只推薦在非常大型 (如有 100+ 個(gè)組件) 的應(yīng)用下才考慮這么做，因?yàn)樵诙嗉?jí)目錄間找來找去，要比在單個(gè) components 目錄下滾動(dòng)查找要花費(fèi)更多的精力。

1.2.7 完整單詞的組件名

組件名應(yīng)該傾向于而不是縮寫。?編輯器中的自動(dòng)補(bǔ)全已經(jīng)讓書寫長命名的代價(jià)非常之低了，而其帶來的明確性卻是非常寶貴的。不常用的縮寫尤其應(yīng)該避免。

components/
|-?StudentDashboardSettings.vue
|-?UserProfileOptions.vue
復(fù)制代碼

1.3 代碼參數(shù)命名

1.3.1 name

組件名應(yīng)該始終是多個(gè)單詞，應(yīng)該始終是 PascalCase 的。?根組件 App 以及?、?之類的 Vue 內(nèi)置組件除外。這樣做可以避免跟現(xiàn)有的以及未來的 HTML 元素相沖突，因?yàn)樗械?HTML 元素名稱都是單個(gè)單詞的。

export?default?{
??name:?'ToDoList',
??//?...
}
復(fù)制代碼

1.3.2 prop

在聲明 prop 的時(shí)候，其命名應(yīng)該始終使用 camelCase，而在模板和 JSX 中應(yīng)該始終使用 kebab-case。我們單純的遵循每個(gè)語言的約定，在 JavaScript 中更自然的是 camelCase。而在 HTML 中則是 kebab-case。

<WelcomeMessage?greeting-text="hi"/>
復(fù)制代碼

export?default?{
??name:?'MyComponent',
??//?...
??props:?{
????greetingText:?{
??????type:?String,
??????required:?true,
??????validator:?function?(value)?{
????????return?['syncing',?'synced',].indexOf(value)?!==?-1
??????}
????}
??}
}
復(fù)制代碼

1.3.3 router

Vue Router Path 命名采用 kebab-case 格式。?用 Snake（如：/user_info）或 camelCase（如：/userInfo)的單詞會(huì)被當(dāng)成一個(gè)單詞，搜索引擎無法區(qū)分語義。

//?bad
{
??path:?'/user_info',?//?user_info?當(dāng)成一個(gè)單詞
??name:?'UserInfo',
??component:?UserInfo,
??meta:?{
????title:?'?-?用戶',
????desc:?''
??}
},

//?good
{
??path:?'/user-info',?//?能解析成?user?info
??name:?'UserInfo',
??component:?UserInfo,
??meta:?{
????title:?'?-?用戶',
????desc:?''
??}
},
復(fù)制代碼

1.3.4 模板中組件

對(duì)于絕大多數(shù)項(xiàng)目來說，在單文件組件和字符串模板中組件名應(yīng)該總是 PascalCase 的，但是在 DOM 模板中總是 kebab-case 的。

?
<MyComponent/>

?
<my-component>my-component>
復(fù)制代碼

1.3.5 自閉合組件

在單文件組件、字符串模板和 JSX 中沒有內(nèi)容的組件應(yīng)該是自閉合的——但在 DOM 模板里永遠(yuǎn)不要這樣做。

<MyComponent/>


<my-component>my-component>
復(fù)制代碼

1.3.6 變量

• 命名方法：camelCase
• 命名規(guī)范：類型 + 對(duì)象描述或?qū)傩缘姆绞?/section>

//?bad
var?getTitle?=?"LoginTable"

//?good
let?tableTitle?=?"LoginTable"
let?mySchool?=?"我的學(xué)校"
復(fù)制代碼

1.3.7 常量

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

const?MAX_COUNT?=?10
const?URL?=?'http://test.host.com'
復(fù)制代碼

1.3.8 方法

• 命名方法：camelCase
• 命名規(guī)范：統(tǒng)一使用動(dòng)詞或者動(dòng)詞 + 名詞形式

//?1、普通情況下，使用動(dòng)詞?+?名詞形式
//?bad
go、nextPage、show、open、login

//?good
jumpPage、openCarInfoDialog

//?2、請(qǐng)求數(shù)據(jù)方法，以?data?結(jié)尾
//?bad
takeData、confirmData、getList、postForm

//?good
getListData、postFormData

//?3、單個(gè)動(dòng)詞的情況
init、refresh
復(fù)制代碼

1.3.9 自定義事件

自定義事件應(yīng)始終使用 kebab-case 的事件名。

不同于組件和 prop，事件名不存在任何自動(dòng)化的大小寫轉(zhuǎn)換。而是觸發(fā)的事件名需要完全匹配監(jiān)聽這個(gè)事件所用的名稱。

this.$emit('my-event')
復(fù)制代碼

"handleDoSomething"?/>
復(fù)制代碼

不同于組件和 prop，事件名不會(huì)被用作一個(gè) JavaScript 變量名或 property 名，所以就沒有理由使用 camelCase 或 PascalCase 了。并且?v-on?事件監(jiān)聽器在 DOM 模板中會(huì)被自動(dòng)轉(zhuǎn)換為全小寫 (因?yàn)?HTML 是大小寫不敏感的)，所以?v-on:myEvent?將會(huì)變成?v-on:myevent——導(dǎo)致?myEvent?不可能被監(jiān)聽到。

• 原生事件參考列表^[1]

由原生事件可以發(fā)現(xiàn)其使用方式如下：

<div
??@blur="toggleHeaderFocus"
??@focus="toggleHeaderFocus"
??@click="toggleMenu"
??@keydown.esc="handleKeydown"
??@keydown.enter="handleKeydown"
??@keydown.up.prevent="handleKeydown"
??@keydown.down.prevent="handleKeydown"
??@keydown.tab="handleKeydown"
??@keydown.delete="handleKeydown"
??@mouseenter="hasMouseHoverHead?=?true"
??@mouseleave="hasMouseHoverHead?=?false">
div>
復(fù)制代碼

而為了區(qū)分_原生事件_和_自定義事件_在 Vue 中的使用，建議除了多單詞事件名使用 kebab-case 的情況下，命名還需遵守為?on?+ 動(dòng)詞?的形式，如下：

<div
??@on-search="handleSearch"
??@on-clear="handleClear"
??@on-clickoutside="handleClickOutside">
div>
復(fù)制代碼

//?子組件
export?default?{
??methods:?{
????handleTriggerItem?()?{
??????this.$emit('on-clear')
????}
??}
}
復(fù)制代碼

1.3.10 事件方法

• 命名方法：camelCase
• 命名規(guī)范：handle + 名稱（可選）+ 動(dòng)詞