Winning前端Vue开发规范

2021-02-14 本文已影响0人 Loong5

[优先级 A：必要的]

这些规则会帮你规避错误，所以学习并接受它们带来的全部代价吧。

[优先级 B：强烈推荐]

这些规则能够在绝大多数工程中改善可读性和开发体验。即使你违反了，代码还是能照常运行，但例外应该尽可能少且有合理的理由。

[优先级 C：推荐]

当存在多个同样好的选项，选任意一个都可以确保一致性。在这些规则里，我们描述了每个选项并建议一个默认的选择。也就是说只要保持一致且理由充分，你可以随意在你的代码库中做出不同的选择。

[优先级 D：谨慎使用]

有些 Vue 特性的存在是为了照顾极端情况或帮助老代码的平稳迁移。当被过度使用时，这些特性会让你的代码难于维护甚至变成 bug 的来源。这些规则是为了给有潜在风险的特性敲个警钟，并说明它们什么时候不应该使用以及为什么。

   ├── src                       项目源码目录
   │   ├── main.js                   入口js文件
   │   ├── App.vue                   根组件
   │   ├── assets                    静态资源目录，公共的静态资源，图片，字体等
   │   │   ├── fonts                     字体资源
   │   │   ├── images                    图片资源
   │   ├── mixin                                     全局混入文件夹
   │   ├── directives                            全局指令文件夹
   │   ├── mock                    mock数据文件夹
   │   │   ├── index.js                   mock入口文件
   │   │   ├── module                                           模块文件夹
   │   │   │   │── user.js                      模块mock数据
   │   ├── service                      api文件夹
   │   │   │   └── service.ubas.js       api文件
   │   ├── components                组件目录
   │   │   ├── common                   公共组文件夹
   │   │   │   │── upload                               上传组件文件夹
   │   │   ├── home                    模块组件文件夹
   │   │   │   └── HomeBanner.vue                主页banner组件
   │   ├── utils                      封装的工具文件夹
   │   │   ├── axios.interceptors.js        Axios拦截器封装
   │   │   ├── constants.js                 接口环境常量
   │   │   ├── views.utils.js               样式逻辑公共方法   
   │   │   ├── vue.common.js                vue全局公共方法
   │   │   ├── vue.http.js                  axios 的封装
   │   ├── store                     数据中心
   │   │   ├── state.js                  state 数据源，数据定义
   │   │   ├── mutations.js              同步修改 state 数据的方法定义
   │   │   ├── mutation-types.js         定义 Mutations 的类型
   │   │   ├── actions.js                异步修改 state 数据的方法定义
   │   │   ├── getters.js                获取数据的方法定义
   │   │   └── index.js                  数据中心入口文件
   │   ├── routes                    前端路由
   │   │   └── index.js
   │   └── views                     页面目录，所有业务逻辑的页面都应该放这里
   │   │   ├── home                      
   │   │   │     ├── HomeIndex.vue
   │   │   │   ├── children
   │     │   │   │   ├── HomeText.vue

0、组件名不为index.vue $\color{red}{必要}$

原则上view文件夹是用来存放路由的页面的,所以应该只存放路由指向的vue组件,或者子路由指向的组件，
并且路由组件不建议直接使用 index.vue 来命名，编辑器切换匹配文件名不友好。

bad

userInfo/
|- index.vue

good

userInfo/
|- userInfoIndex.vue

1、组件名为多个单词 $\color{red}{必要}$

组件名应该始终是多个单词的，根组件 App 除外。
这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。

bad

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

good

Vue.component('todoItem', {
  // ...
})
export default {
  name: 'TodoItem',
  // ...
}

2、组件数据 $\color{red}{必要}$

组件的 data 必须是一个函数。
当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。

(如果data是一个函数的话，这样每复用一次组件，就会返回一份新的data，类似于给每个组件实例创建一个私有的数据空间，让各个组件实例维护各自的数据。而单纯的写成对象形式，就使得所有组件实例共用了一份data，就会造成一个变了全都会变的结果)

bad

Vue.component('someComp', {
  data: {
    foo: 'bar'
  }
})
export default {
  data: {
    foo: 'bar'
  }
}

good

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

3、Prop 定义 $\color{red}{必要}$

Prop 定义应该尽量详细。
在你提交的代码中，prop 的定义应该尽量详细，至少需要指定其类型。
细致的prop 定义有两个好处：
（1）它们写明了组件的 API，所以很容易看懂组件的用法；
（2）在开发环境下，如果向一个组件提供格式不正确的 prop，Vue 将会告警，以帮助你捕获潜在的错误来源。

bad

props: ['status']

good

props: {
  status: {
    type: String,
    required: true,
    validator: function (value) {
 
    }
  }
}

4、为 `v-for` 设置键值 $\color{red}{必要}$

在组件上总是必须用 key 配合 v-for ，以便维护内部组件及其子树的状态。

bad

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

good

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

5、避免 `v-if` 和 `v-for`用在一起 $\color{red}{必要}$

永远不要把 v-if 和 v-for同时用在同一个元素上。

一般我们在两种常见的情况下会倾向于这样做：

为了过滤一个列表中的项目 (比如 v-for="user in users" v-if="user.isActive")。在这种情形下，请将 users 替换为一个计算属性 (比如 activeUsers)，让其返回过滤后的列表。

为了避免渲染本应该被隐藏的列表 (比如 v-for="user in users" v-if="shouldShowUsers")。这种情形下，请将 v-if 移动至容器元素上 (比如 ul、ol)。

bad

<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
<ul>
  <li
    v-for="user in users"
    v-if="shouldShowUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

good

<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
<ul v-if="shouldShowUsers">
  <li
    v-for="user in users"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

6、为组件样式设置作用域 $\color{red}{必要}$

对于应用来说，顶级App 组件和布局组件中的样式可以是全局的，但是其它所有组件都应该是有作用域的。
对于组件库，我们应该更倾向于选用基于 class 的策略而不是 scoped 特性。
使用唯一的class 名可以帮你确保那些三方库的CSS 不会运用在你自己的HTML上。

bad

<template>
  <button class="btn btn-close">X</button>
</template>

<style>
.btn-close {
  background-color: red;
}
</style>

good

<template>
  <button class="button button-close">X</button>
</template>

<!-- 使用 `scoped` attribute -->
<style scoped>
.button {
  border: none;
  border-radius: 2px;
}

.button-close {
  background-color: red;
}
</style>
<template>
  <button :class="[$style.button, $style.buttonClose]">X</button>
</template>


<!-- 使用 BEM 约定 -->
<style>
.c-Button {
  border: none;
  border-radius: 2px;
}

.c-Button--close {
  background-color: red;
}
</style>

7、私有属性名 $\color{red}{必要}$

在插件、混入等扩展中始终为自定义的私有属性使用 $_前缀。并附带一个命名空间以回避和其它作者的冲突 (比如 $_yourPluginName_)。

bad

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

good

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

8、单文件组件文件的大小写 $\color{red}{必要}$

单文件组件的文件名应该要么始终是小驼峰。

bad

components/
|- MyComponent.vue

good

components/
|- myComponent.vue

9、基础组件名。 $\color{red}{必要}$

应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头，比如 Base、App 。

bad

components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue

good

components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue

10、紧密耦合的组件名 $\color{red}{必要}$

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。
如果一个组件只在某个父组件的场景下有意义，这层关系应该体现在其名字上。因为编辑器通常会按字母顺序组织文件，所以这样做可以把相关联的文件排在一起。

bad

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

good

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

components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

11、组件名中的单词顺序 $\color{red}{必要}$

组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。

bad

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

good

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

12、自闭合组件 $\color{red}{必要}$

在单文件组件、字符串模板和JSX中没有内容的组件应该是自闭合的，但在 DOM 模板里永远不要这样做。
HTML 并不支持自闭合的自定义元素

bad

<!-- 在 DOM 模板中 -->
<my-component/>

good

<!-- 在 DOM 模板中 -->
<my-component></my-component>

13、模板中的组件名大小写 $\color{red}{必要}$

由于 HTML 是大小写不敏感的，在 DOM 模板中必须仍使用 kebab-case。

bad

<!-- 在 DOM 模板中 -->
<MyComponent></MyComponent>

good

<!-- 在所有地方 -->
<my-component></my-component>

14、JS/JSX 中的组件名大小写 $\color{red}{必要}$

JS/[JSX中的组件名应该始终是 camelCase的，尽管在较为简单的应用中只使用 Vue.component 进行全局组件注册时，可以使用 kebab-case 字符串。

bad

import MyComponent from './MyComponent.vue'
export default {
  name: 'MyComponent',
  // ...
}

good

import myComponent from './myComponent.vue'
export default {
  name: 'myComponent',
  // ...
}

15、完整单词的组件名 $\color{red}{必要}$

组组件名应该倾向于完整单词而不是缩写。

bad

components/
|- SdSettings.vue
|- UProfOpts.vue

good

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue

16、Prop 名大小写 $\color{red}{必要}$

组组件名应该倾向于完整单词而不是缩写。

bad

props: {
  'greeting-text': String
}
<WelcomeMessage greetingText="hi"/>

good

props: {
  greetingText: String
}
<WelcomeMessage greeting-text="hi"/>

17、模板中简单的表达式 $\color{red}{必要}$

组件模板应该只包含简单的表达式，复杂的表达式则应该重构为计算属性或方法。

bad

{{
  fullName.split(' ').map(function (word) {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}

good

<!-- 在模板中 -->
{{ normalizedFullName }}
// 复杂表达式已经移入一个计算属性
computed: {
  normalizedFullName: function () {
    return this.fullName.split(' ').map(function (word) {
      return word[0].toUpperCase() + word.slice(1)
    }).join(' ')
  }
}

18、带引号的 `attribute`值 $\color{red}{必要}$

非空 HTML attribute 值应该始终带双引号。

bad

<input type=text>
<AppSidebar :style={width:sidebarWidth+'px'}>

good

<input type="text">
<AppSidebar :style="{ width: sidebarWidth + 'px' }">

19、指令缩写 $\color{red}{必要}$

指令缩写 (用 : 表示 v-bind:、用 @ 表示 v-on: ) 。

bad

<input
  v-bind:value="newTodoText"
  :placeholder="newTodoInstructions"
>
<input
  v-on:input="onInput"
  @focus="onFocus"
>
<template v-slot:header>
  <h1>Here might be a page title</h1>
</template>

good

<input
  :value="newTodoText"
  :placeholder="newTodoInstructions"
>
<input
  @input="onInput"
  @focus="onFocus"
>

20、简单的计算属性 $\color{red}{强烈推荐}$

应该把复杂计算属性分割为尽可能多的更简单的 property。

bad

computed: {
  price: function () {
    var basePrice = this.manufactureCost / (1 - this.profitMargin)
    return (
      basePrice -
      basePrice * (this.discountPercent || 0)
    )
  }
}

good

computed: {
  basePrice: function () {
    return this.manufactureCost / (1 - this.profitMargin)
  },
  discount: function () {
    return this.basePrice * (this.discountPercent || 0)
  },
  finalPrice: function () {
    return this.basePrice - this.discount
  }
}

21、多个 attribute 的元素 $\color{red}{强烈推荐}$

多个 attribute 的元素应该分多行撰写，每个 attribute 一行。

bad

<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
<MyComponent foo="a" bar="b" baz="c"/>

good

<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

22、单例组件名 $\color{red}{强烈推荐}$

只应该拥有单个活跃实例的组件应该以 The 前缀命名，以示其唯一性。
这不意味着组件只可用于一个单页面，而是每个页面只使用一次。这些组件永远不接受任何 prop，因为它们是为你的应用定制的，而不是它们在你的应用中的上下文。如果你发现有必要添加 prop，那就表明这实际上是一个可复用的组件，只是目前在每个页面里只使用一次。

bad

components/
|- Heading.vue
|- MySidebar.vue

good

components/
|- TheHeading.vue
|- TheSidebar.vue

23、`scoped` 中的元素选择器 $\color{red}{谨慎使用}$

在 scoped 样式中，类选择器比元素选择器更好，因为大量使用元素选择器是很慢的。

为了给样式设置作用域，Vue 会为元素添加一个独一无二的 attribute，例如 data-v-f3f3eg9。然后修改选择器，使得在匹配选择器的元素中，只有带这个attribute 才会真正生效 (比如 button[data-v-f3f3eg9])。
问题在于大量的元素和 attribute 组合的选择器 (比如 button[data-v-f3f3eg9]) 会比类和 attribute 组合的选择器慢，所以应该尽可能选用类选择器。

bad

<template>
  <button>X</button>
</template>

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

good

<template>
  <button class="btn btn-close">X</button>
</template>

<style scoped>
.btn-close {
  background-color: red;
}
</style>

24、隐性的父子组件通信 $\color{red}{谨慎使用}$

应该优先通过prop 和事件进行父子组件之间的通信，而不是 this.$parent或变更prop。

一个理想的 Vue 应用是prop 向下传递，事件向上传递的。遵循这一约定会让你的组件更易于理解。然而，在一些边界情况下 prop的变更或 this.$parent 能够简化两个深度耦合的组件。
问题在于，这种做法在很多简单的场景下可能会更方便。但请当心，不要为了一时方便 (少写代码) 而牺牲数据流向的简洁性 (易于理解)。

bad

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: '<input v-model="todo.text">'
})

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  methods: {
    removeTodo () {
      var vm = this
      vm.$parent.todos = vm.$parent.todos.filter(function (todo) {
        return todo.id !== vm.todo.id
      })
    }
  },
  template: `
    <span>
      {{ todo.text }}
      <button @click="removeTodo">
        X
      </button>
    </span>
  `
})

good

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: `
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: `
    <span>
      {{ todo.text }}
      <button @click="$emit('delete')">
        X
      </button>
    </span>
  `
})

25、没有在 `v-if/v-else-if/v-else` 中使用 key $\color{red}{谨慎使用}$

如果一组 v-if + v-else 的元素类型相同，最好使用 key (比如两个 <div> 元素)。

默认情况下，Vue 会尽可能高效的更新 DOM。这意味着其在相同类型的元素之间切换时，会修补已存在的元素，而不是将旧的元素移除然后在同一位置添加一个新元素。如果本不相同的元素被识别为相同，则会出现意料之外的结果。

bad

<div v-if="error">
  错误：{{ error }}
</div>
<div v-else>
  {{ results }}
</div>

good

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

26、全局状态管理 $\color{red}{谨慎使用}$

应该优先通过 Vuex管理全局状态，而不是通过 this.$root 或一个全局事件总线。
通过 this.$root 在很多简单的情况下都是很方便的，但是并不适用于绝大多数的应用。

Vuex 是 Vue 的官方类 flux 实现，其提供的不仅是一个管理状态的中心区域，还是组织、追踪和调试状态变更的好工具。

bad

// main.js
new Vue({
  data: {
    todos: []
  },
  created: function () {
    this.$on('remove-todo', this.removeTodo)
  },
  methods: {
    removeTodo: function (todo) {
      var todoIdToRemove = todo.id
      this.todos = this.todos.filter(function (todo) {
        return todo.id !== todoIdToRemove
      })
    }
  }
})

good

// store/modules/todos.js
export default {
  state: {
    list: []
  },
  mutations: {
    REMOVE_TODO (state, todoId) {
      state.list = state.list.filter(todo => todo.id !== todoId)
    }
  },
  actions: {
    removeTodo ({ commit, state }, todo) {
      commit('REMOVE_TODO', todo.id)
    }
  }
}

<!-- TodoItem.vue -->
<template>
  <span>
    {{ todo.text }}
    <button @click="removeTodo(todo)">
      X
    </button>
  </span>
</template>

<script>
import { mapActions } from 'vuex'

export default {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  methods: mapActions(['removeTodo'])
}
</script>

Winning前端Vue开发规范

[优先级 A：必要的]

[优先级 B：强烈推荐]

[优先级 C：推荐]

[优先级 D：谨慎使用]

0、组件名不为index.vue

bad

good

1、组件名为多个单词

bad

good

2、组件数据

bad

good

3、Prop 定义

bad

good

4、为 v-for 设置键值

bad

good

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

bad

good

6、为组件样式设置作用域

bad

good

7、私有属性名

bad

good

8、单文件组件文件的大小写

bad

good

9、基础组件名。

bad

good

10、紧密耦合的组件名

bad

good

11、组件名中的单词顺序

bad

good

12、自闭合组件

bad

good

13、模板中的组件名大小写

bad

good

14、JS/JSX 中的组件名大小写

bad

good

15、完整单词的组件名

bad

good

16、Prop 名大小写

bad

good

17、模板中简单的表达式

bad

good

18、带引号的 attribute值

bad

good

19、指令缩写

bad

good

20、简单的计算属性

bad

good

21、多个 attribute 的元素

bad

good

22、单例组件名

bad

good

23、scoped 中的元素选择器

bad

good

24、隐性的父子组件通信

bad

good

0、组件名不为index.vue $\color{red}{必要}$

1、组件名为多个单词 $\color{red}{必要}$

2、组件数据 $\color{red}{必要}$

3、Prop 定义 $\color{red}{必要}$

4、为 `v-for` 设置键值 $\color{red}{必要}$

5、避免 `v-if` 和 `v-for`用在一起 $\color{red}{必要}$

6、为组件样式设置作用域 $\color{red}{必要}$

7、私有属性名 $\color{red}{必要}$

8、单文件组件文件的大小写 $\color{red}{必要}$

9、基础组件名。 $\color{red}{必要}$

10、紧密耦合的组件名 $\color{red}{必要}$

11、组件名中的单词顺序 $\color{red}{必要}$

12、自闭合组件 $\color{red}{必要}$

13、模板中的组件名大小写 $\color{red}{必要}$

14、JS/JSX 中的组件名大小写 $\color{red}{必要}$

15、完整单词的组件名 $\color{red}{必要}$

16、Prop 名大小写 $\color{red}{必要}$

17、模板中简单的表达式 $\color{red}{必要}$

18、带引号的 `attribute`值 $\color{red}{必要}$

19、指令缩写 $\color{red}{必要}$

20、简单的计算属性 $\color{red}{强烈推荐}$

21、多个 attribute 的元素 $\color{red}{强烈推荐}$

22、单例组件名 $\color{red}{强烈推荐}$

23、`scoped` 中的元素选择器 $\color{red}{谨慎使用}$

24、隐性的父子组件通信 $\color{red}{谨慎使用}$

25、没有在 `v-if/v-else-if/v-else` 中使用 key $\color{red}{谨慎使用}$

26、全局状态管理 $\color{red}{谨慎使用}$