Vue.js 組件編碼規(guī)范
提供一種統(tǒng)一的編碼規(guī)范來(lái)編寫 Vue.js 代碼。這使得代碼具有如下的特性：
* 其它開(kāi)發(fā)者或是團(tuán)隊(duì)成員更容易閱讀和理解。* IDEs 更容易理解代碼，從而提供高亮、格式化等輔助功能* 更容易使用現(xiàn)有的工具*?更容易實(shí)現(xiàn)緩存以及代碼包的分拆
基于模塊開(kāi)發(fā)
始終基于模塊的方式來(lái)構(gòu)建你的 app，每一個(gè)子模塊只做一件事情。Vue.js 的設(shè)計(jì)初衷就是幫助開(kāi)發(fā)者更好的開(kāi)發(fā)界面模塊。一個(gè)模塊是應(yīng)用程序中獨(dú)立的一個(gè)部分。
????HOW?
每一個(gè) Vue 組件(等同于模塊)首先必須專注于解決一個(gè) 單一的問(wèn)題 ， 獨(dú)立的 , 可復(fù)用的 , 微小的 and 可測(cè)試的 。如果你的組件做了太多的事或是變得臃腫，請(qǐng)將其拆分成更小的組件并保持單一的原則。一般來(lái)說(shuō)，盡量保證每一個(gè)文件的代碼行數(shù)不要超過(guò) 100 行。也請(qǐng)保證組件可獨(dú)立的運(yùn)行。比較好的做法是增加一個(gè)單獨(dú)的 demo 示例。
Vue組件命名
組件的命名需遵從以下原則：
* 有意義的 : 不過(guò)于具體，也不過(guò)于抽象* 簡(jiǎn)短 : 2 到 3 個(gè)單詞* 具有可讀性 : 以便于溝通交流* 必須符合 自定義元素規(guī)范 : 使用連字符 分隔單詞，切勿使用保留字。* app- 前綴作為命名空間 : 如果非常通用的話可使用一個(gè)單詞來(lái)命名，這樣可以方便于其它項(xiàng)目里復(fù)用。
WHY?
* 組件是通過(guò)組件名來(lái)調(diào)用的。所以組件名必須簡(jiǎn)短、富有含義并且具有可讀性。HOW?
<app-header>app-header><user-list>user-list><range-slider>range-slider><btn-group>btn-group><ui-slider>ui-slider><slider>slider>
組件表達(dá)式簡(jiǎn)單化
Vue.js 的表達(dá)式是 100% 的 Javascript 表達(dá)式。這使得其功能性很強(qiáng)大，但也帶來(lái)潛在的復(fù)雜性。因此，你應(yīng)該盡量 保持表達(dá)式的簡(jiǎn)單化?.
WHY?
* 復(fù)雜的行內(nèi)表達(dá)式難以閱讀。* 行內(nèi)表達(dá)式是不能夠通用的，這可能會(huì)導(dǎo)致重復(fù)編碼的問(wèn)題。* IDE 基本上不能識(shí)別行內(nèi)表達(dá)式語(yǔ)法，所以使用行內(nèi)表達(dá)式 IDE 不能提供自動(dòng)補(bǔ)全和語(yǔ)法校驗(yàn)功能。
HOW?
如果你發(fā)現(xiàn)寫了太多復(fù)雜并難以閱讀的行內(nèi)表達(dá)式，那么可以使用 method 或是 computed 屬性來(lái)替代其功能。
<template><h1>{{ `${year}-${month}` }}h1>template><script type="text/javascript">export default {computed: {month() {return this.twoDigits((new Date()).getUTCMonth() + 1);},year() {return (new Date()).getUTCFullYear();}},methods: {twoDigits(num) {return ('0' + num).slice(-2);}},};script><template><h1>{{ `${(new Date()).getUTCFullYear()}-${('0' + ((new Date()).getUTCMonth()+1)).slice(-2)}` }}h1>template><template><h1>{{ `${year}-${month}` }}h1>template><script type="text/javascript">export default {computed: {month() {return this.twoDigits((new Date()).getUTCMonth() + 1);},year() {return (new Date()).getUTCFullYear();}},methods: {twoDigits(num) {return ('0' + num).slice(-2);}},};script><template><h1>{{ `${(new Date()).getUTCFullYear()}-${('0' + ((new Date()).getUTCMonth()+1)).slice(-2)}` }}h1>template>
組件props原子化
雖然 Vue.js 支持傳遞復(fù)雜的 JavaScript 對(duì)象通過(guò) props 屬性，但是你應(yīng)該盡可能的使用原始類型的數(shù)據(jù)。盡量只使用 JavaScript 原始類型 (字符串、數(shù)字、布爾值) 和 函數(shù)。盡量避免復(fù)雜的對(duì)象。
WHY?
* 使得組件 API 清晰直觀* 只使用原始類型和函數(shù)作為 props 使得組件的 API 更接近于 HTML(5) 原生元素。* 其它開(kāi)發(fā)者更好的理解每一個(gè) prop 的含義，作用* 傳遞過(guò)于復(fù)雜的對(duì)象使得我們不能夠清楚的知道哪些屬性或方法被自定義組件使用，這使得代碼難以重構(gòu)和維護(hù)。
HOW?
組件的每一個(gè)屬性單獨(dú)使用一個(gè) props，并且使用函數(shù)或是原始類型的值。
<range-slider:values="[10, 20]"min="0"max="100"step="5":on-slide="updateInputs":on-end="updateResults">range-slider><range-slider :config="complexConfigObject">range-slider>
驗(yàn)證組件的props
在 Vue.js 中，組件的 props 即 API，一個(gè)穩(wěn)定并可預(yù)測(cè)的 API 會(huì)使得你的組件更容易被其他開(kāi)發(fā)者使用。組件 props 通過(guò)自定義標(biāo)簽的屬性來(lái)傳遞。屬性的值可以是 Vue.js 字符串( :attr="value" 或v-bind:attr="value" )或是不傳。你需要保證組件的 props 能應(yīng)對(duì)不同的情況。
WHY?
驗(yàn)證組件 props 可以保證你的組件永遠(yuǎn)是可用的(防御性編程)。即使其他開(kāi)發(fā)者并未按照你預(yù)想的方法使用時(shí)也不會(huì)出錯(cuò)。
HOW?
* 提供默認(rèn)值* 使用 type 屬性 校驗(yàn)類型* 使用 props 之前先檢查該 prop 是否存在
<template><input type="range" v-model="value" :max="max" :min="min">template><script type="text/javascript">export default {props: {max: {type: Number, // 這里添加了數(shù)字類型的校驗(yàn)default() { return 10; },},min: {type: Number,default() { return 0; },},value: {type: Number,default() { return 4; },},},};script>
將this賦值給component變量
在 Vue.js 組件上下文中， this 指向了組件實(shí)例。因此當(dāng)你切換到了不同的上下文時(shí)，要確保this 指向一個(gè)可用的 component 變量。換句話說(shuō)，不要在編寫這樣的代碼 const self = this; ，而是應(yīng)該直接使用變量 component。
WHY?
* 將組件 this 賦值給變量 component 可用讓開(kāi)發(fā)者清楚的知道任何一個(gè)被使用的地方，它代表的是組件實(shí)例。HOW?
<script type="text/javascript">export default {methods: {hello() {return 'hello';},printHello() {console.log(this.hello());},},};script><script type="text/javascript">export default {methods: {hello() {return 'hello';},printHello() {const self = this; // 沒(méi)有必要console.log(self.hello());},},};script>
組件結(jié)構(gòu)化
按照一定的結(jié)構(gòu)組織，使得組件便于理解.
WHY?
* 導(dǎo)出一個(gè)清晰、組織有序的組件，使得代碼易于閱讀和理解。同時(shí)也便于標(biāo)準(zhǔn)化。* 按首字母排序properties, data, computed, watches 和 methods使得這些對(duì)象內(nèi)的屬性便于查找。* 合理組織，使得組件易于閱讀。(name; extends; props, data and computed; components; watch and methods; lifecycle methods, 等.);* 使用 name 屬性。借助于 vue devtools 可以讓你更方便的測(cè)試* 合理的 CSS 結(jié)構(gòu)，如 BEM 或 rscss -;* 使用單文件 .vue 文件格式來(lái)組件代碼
HOW?
組件結(jié)構(gòu)化
<template lang="html"><div class="Ranger__Wrapper">div>template><script type="text/javascript">export default {// 不要忘記了 name 屬性name: 'RangeSlider',// 組合其它組件extends: {},// 組件屬性、變量props: {bar: {}, // 按字母順序foo: {},fooBar: {},},// 變量data() {},computed: {},// 使用其它組件components: {},// 方法watch: {},methods: {},// 生命周期函數(shù)beforeCreate() {},mounted() {},};script><style scoped>.Ranger__Wrapper { /* ... */ }style>
組件事件命名
Vue.js 提供的處理函數(shù)和表達(dá)式都是綁定在 ViewModel 上的，組件的每一個(gè)事件都應(yīng)該按照一個(gè)好的命名規(guī)范來(lái)，這樣可以避免不少的開(kāi)發(fā)問(wèn)題
WHY?
* 開(kāi)發(fā)者可以隨意給事件命名，即使是原生事件的名字，這樣會(huì)帶來(lái)迷惑性。* 過(guò)于寬松的事件命名可能與 DOM模板不兼容 。
HOW?
* 事件命名也連字符命名* 一個(gè)事件的名字對(duì)應(yīng)組件外的一組意義操作，如：upload-success, upload-error 以及 dropzone-upload-success, dropzone-upload-error (如果需要前綴的話)。* 事件命名應(yīng)該以動(dòng)詞(如 client-api-load) 或是 形容詞(如 drive-upload-success)結(jié)尾。( 出處 )
避免this.$parent
Vue.js 支持組件嵌套，并且子組件可訪問(wèn)父組件的上下文。訪問(wèn)組件之外的上下文違反了 基于模塊開(kāi)發(fā) 的 第一原則 。因此你應(yīng)該盡量避免使用 this.$parent 。
WHY?
* 組件必須相互保持獨(dú)立，Vue 組件也是。如果組件需要訪問(wèn)其父層的上下文就違反了該原則。* 如果一個(gè)組件需要訪問(wèn)其父組件的上下文，那么該組件將不能再其它上下文中復(fù)用。
HOW?
* 通過(guò) props 將值傳遞給子組件* 通過(guò) props 傳遞回調(diào)函數(shù)給子組件來(lái)達(dá)到調(diào)用父組件方法的目的* 通過(guò)在子組件觸發(fā)事件來(lái)通知父組件
謹(jǐn)慎使用this.$refs
Vue.js 支持通過(guò) ref 屬性來(lái)訪問(wèn)其它組件和 HTML 元素。并通過(guò) this.$refs 可以得到組件或 HTML 元素的上下文。在大多數(shù)情況下，通過(guò) this.$refs 來(lái)訪問(wèn)其它組件的上下文是可以避免的。在使用的的時(shí)候你需要注意避免調(diào)用了不恰當(dāng)?shù)慕M件 API，所以應(yīng)該盡量避免使用 this.$refs 。
WHY?
* 組件必須是保持獨(dú)立的，如果一個(gè)組件的 API 不能夠提供所需的功能，那么這個(gè)組件在設(shè)計(jì)、實(shí)現(xiàn)上是有問(wèn)題的。* 組件的屬性和事件必須足夠的給大多數(shù)的組件使用
HOW?
* 提供良好的組件 API* 總是關(guān)注于組件本身的目的* 拒絕定制代碼。如果你在一個(gè)通用的組件內(nèi)部編寫特定需求的代碼，那么代表這個(gè)組件的 API 不夠通用，或者你可能需要一個(gè)新的組件來(lái)應(yīng)對(duì)該需求* 檢查所有的 props 是否有缺失的，如果有提一個(gè) issue 或是完善這個(gè)組件* 檢查所有的事件。子組件向父組件通信一般是通過(guò)事件來(lái)實(shí)現(xiàn)的，但是大多數(shù)的開(kāi)發(fā)者更多的關(guān)注于 props 從忽視了這點(diǎn)。* Props向下傳遞，事件向上傳遞！。以此為目標(biāo)升級(jí)你的組件，提供良好的 API 和 獨(dú)立性。* 當(dāng)遇到 props 和 events 難以實(shí)現(xiàn)的功能時(shí)，通過(guò) this.$refs 來(lái)實(shí)現(xiàn)。* 當(dāng)需要操作 DOM 無(wú)法通過(guò)指令來(lái)做的時(shí)候可使用 this..$ref 而不是 JQuery , document.getElement* , document.queryElement 。
<range :max="max":min="min"@current-value="currentValue":step="1">range><modal ref="basicModal"><h4>Basic Modalh4><button class="primary" @click="$refs.basicModal.close()">Closebutton>modal><button @click="$refs.basicModal.open()">Open modalbutton><template><div v-show="active">div>template><script>export default {// ...data() {return {active: false,};},methods: {open() {this.active = true;},hide() {this.active = false;},},// ...};script><template><range :max="max":min="min"ref="range":step="1">range>template><script>export default {// ...methods: {getRangeCurrentValue() {return this.$refs.range.currentValue;},},// ...};script>
使用組件名作為樣式作用域空間
Vue.js 的組件是自定義元素，這非常適合用來(lái)作為樣式的根作用域空間。可以將組件名作為 css 類的命名空間。
WHY?
* 給樣式加上作用域空間可以避免組件樣式影響外部的樣式* 保持模塊名、目錄名、樣式根作用域名一樣，可以很好的將其關(guān)聯(lián)起來(lái)，便于開(kāi)發(fā)者理解。
HOW?
使用組件名作為樣式命名的前綴，可基于 BEM 或 OOCSS 范式。同時(shí)給style標(biāo)簽加上 scoped 屬性。加上 scoped 屬性編譯后會(huì)給組件的 class 自動(dòng)加上唯一的前綴從而避免樣式的沖突。
<style scoped>/* 推薦 */.MyExample { }.MyExample li { }.MyExample__item { }/* 避免 */.My-Example { } /* not scoped to component or module name, not BEM compliant */style>
提供組件API文檔
使用 Vue.js 組件的過(guò)程中會(huì)創(chuàng)建 Vue 組件實(shí)例，這個(gè)實(shí)例是通過(guò)自定義屬性配置的。為了便于其他開(kāi)發(fā)者使用該組件，對(duì)于這些自定義屬性即組件API應(yīng)該在 README.md 文件中進(jìn)行說(shuō)明。
WHY?
* 良好的文檔可以讓開(kāi)發(fā)者比較容易的對(duì)組件有一個(gè)整體的認(rèn)識(shí)，而不用去閱讀組件的源碼，也更方便開(kāi)發(fā)者使用* 組件配置屬性即組件的 API，對(duì)于組件的用戶來(lái)說(shuō)他們更感興趣的是 API 而不是實(shí)現(xiàn)原理。* 正式的文檔會(huì)告訴開(kāi)發(fā)者組件 API 變更以及向后的兼容性情況* README.md 是標(biāo)準(zhǔn)的我們應(yīng)該首先閱讀的文檔文件。代碼托管網(wǎng)站 (github/bitbucket/gitlab 等) 會(huì)默認(rèn)在倉(cāng)庫(kù)中展示 該文件作為倉(cāng)庫(kù)的介紹
HOW?
在模塊目錄中添加 README.md 文件：
range-slider/ ├── range-slider.vue ├── range-slider.less └── README.md 在 README 文件中說(shuō)明模塊的功能以及使用場(chǎng)景。對(duì)于 vue 組件來(lái)說(shuō)，比較有用的描述是組件的自定義屬性即 API 的描述介紹。
Range slider功能
range slider 組件可通過(guò)拖動(dòng)的方式來(lái)設(shè)置一個(gè)給定范圍內(nèi)的數(shù)值。該模塊使用 noUiSlider 來(lái)實(shí)現(xiàn)夸瀏覽器和 touch 功能的支持。
如何使用
range-slider支持如下的自定義屬性：attribute type description min Number 可拖動(dòng)的最小值. max Number 可拖動(dòng)的最大值. values Number[] optional 包含最大值和最小值的數(shù)組. 如. values="[10, 20]" . Defaults to [opts.min, opts.max] . step Number optional 增加減小的數(shù)值單位，默認(rèn)為 1. on-slide Function optional 用戶拖動(dòng)開(kāi)始按鈕或者結(jié)束按鈕時(shí)的回調(diào)函數(shù)，函數(shù)接受 (values, HANDLE) 格式的參數(shù)。如：on-slide={ updateInputs } , component.updateInputs = (values, HANDLE) => { const value = values[HANDLE]; } . on-end Function optional 當(dāng)用戶停止拖動(dòng)時(shí)觸發(fā)的回調(diào)函數(shù)，函數(shù)接受 (values, HANDLE) 格式的參數(shù)。如需要自定義 slider 的樣式可參考 noUiSlider 文檔
提供組件demo
添加 index.html 文件作為組件的 demo 示例，并提供不同配置情況的效果，說(shuō)明組件是如何使用的
WHY?
* demo 可以說(shuō)明組件是獨(dú)立可使用的* demo 可以讓開(kāi)發(fā)者預(yù)覽組件的功能效果* demo 可以展示組件各種配置參數(shù)下的功能
對(duì)組件文件進(jìn)行代碼校驗(yàn)
代碼校驗(yàn)可以保持代碼的統(tǒng)一性以及追蹤語(yǔ)法錯(cuò)誤。.vue 文件可以通過(guò)使用 eslint-plugin-html 插件來(lái)校驗(yàn)代碼。你可以通過(guò) vue-cli 來(lái)開(kāi)始你的項(xiàng)目， vue-cli 默認(rèn)會(huì)開(kāi)啟代碼校驗(yàn)功能。
WHY?
* 保證所有的開(kāi)發(fā)者使用同樣的編碼規(guī)范。* 更早的感知到語(yǔ)法錯(cuò)誤
HOW?
為了校驗(yàn)工具能夠校驗(yàn) *.vue 文件，你需要將代碼編寫在script標(biāo)簽中，并使，因?yàn)樾ｒ?yàn)工具無(wú)法理解行內(nèi)表達(dá)式，配置校驗(yàn)工具可以訪問(wèn)全局變量 vue 和組件的 props 。ESLint ESLint 需要通過(guò) ESLint HTML 插件 來(lái)抽取組件中的代碼。通過(guò) .eslintrc 文件來(lái)配置 ESlint，這樣 IED 可以更好的理解校驗(yàn)配置項(xiàng)。ESlint，這樣.
{"extends": "eslint:recommended","plugins": ["html"],"env": {"browser": true},"globals": {"opts": true,"vue": true}}
運(yùn)行 ESLint
eslint src/**/*.vueJSHintJSHint 可以解析 HTML (使用 --extra-ext 命令參數(shù)) 和 抽取代碼（使用 --extract=auto 命令參數(shù)).通過(guò) .jshintrc 文件來(lái)配置 ESlint，這樣 IED 可以更好的理解校驗(yàn)配置項(xiàng)。{"browser": true,"predef": ["opts", "vue"]}運(yùn)行 JSHintjshint --config modules/.jshintrc --extra-ext=html --extract=auto modules/注：JSHint 不接受 vue 擴(kuò)展名的文件，只支持 html 。