• Vue代码规范

    Vue代码规范

    认识代码规范

    先来思考两个问题：

    1. 什么是代码规范？
    2. 为什么需要代码规范？

    如果你是一个经验丰富的前端开发，你一定接触过这样的老项目：变量名是 abc，fds 这种随意起的，或者是 name1, name2 这种带数字起名，这样的变量不加注释，鬼都不知道它是干什么的。

    这类代码就是一种典型的不规范代码。这样的代码除了让我们开发人员情绪暴躁，最重要的问题是，它极大的降低了团队协作的效率和程序质量。

    在团队协作过程中，当组内其他人需要使用或 review 你的代码，看到这种情况，除了喷你，还要花费大量时间了解你写的是什么。同时这样非常容易造成变量冲突，带来未知隐患，调试困难等问题，甚至可以看出一个程序员的编码态度和专业程度。

    当然，代码规范包含很多方面，变量命名规范只是最基础的规范。不规范的地方越多，程序质量越低，团队协作的效率也就会越低。

    工程目录

    • 全局通用的组件放在 /src/components/ 下。
    • 页面/视图组件放在 /src/views/ 下。
    • 全局公共指令、过滤器（多于三个文件以上引用）分别放在 src/ 目录下的 directives/、filters/。
    • 当页面文件具有私有组件、指令、过滤器时，则建立一个与页面同名的目录，页面文件更名为 index.vue，然后在该目录下创建私有 ./components 等文件夹。

    例如：

    src/
├── App.vue
├── assets
├── main.js
├── components                     # 全局通用组件
├── directive                      # 全局公共指令
├── filters                        # 全局公共过滤器
└── views                          # 页面/视图
    ├── login
    │   ├── components             # 私有组件
    │   └── index.vue
    └── profile
        ├── components             # 私有组件
        └── index.vue

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14

    命名规范

    1.1 通用文件与文件夹

    1.1.0 市面上常用的命名规范
    • camelCase（小驼峰式命名法 —— 首字母小写）
    • PascalCase（大驼峰式命名法 —— 首字母大写）
    • kebab-case（短横线/中划线命名法）
    • Snake（下划线命名法）
    1.1.1 项目名

    全部采用小写方式， 以短横线分隔。例：my-project-name。

    1.1.2 目录名

    参照项目命名规则，有复数结构时，要采用复数命名法。例：docs、assets、components、directives、mixins、utils、views。

    1.1.3 图片文件名

    全部采用小写方式， 优先选择单个单词命名，多个单词命名以下划线分隔。

    banner_sina.gif
menu_aboutus.gif
menutitle_news.gif
logo_police.gif
logo_national.gif
pic_people.jpg

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    1.1.4 HTML 文件名

    全部采用小写方式， 优先选择单个单词命名，多个单词命名以下划线分隔。

    |- error_report.html
|- success_report.html

    • 1
    • 2
    1.1.5 CSS 文件名

    全部采用小写方式， 优先选择单个单词命名，多个单词命名以短横线分隔。

    |- normalize.less
|- base.less
|- date-picker.scss
|- input-number.scss

    • 1
    • 2
    • 3
    • 4

    1.1.6 JavaScript 文件名

    全部采用小写方式， 优先选择单个单词命名，多个单词命名以短横线分隔。

    |- index.js
|- plugin.js
|- util.js
|- date-util.js
|- account-model.js
|- collapse-transition.js

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6

    上述规则可以快速记忆为“静态文件下划线，编译文件短横线”。

    1.2 Vue特色文件夹

    在 Vue 工程中，这是对通用文件与文件夹命名规范的补充。

    1.2.1 位于 components/ 下的直接子文件夹
    • 代表着这类模块的类别。
    • 由名词组成（例如：Charts/）。
    • 最好只有一个单词，特殊情况可例外（good: Car/，Order/，Cart/）（bad: CarInfo/，CarPage/）。
    • 如果有两个以上单词，采用 PascalBase 大驼峰 风格（例如：BackToTop/）
    1.2.2 位于 views/ 下的文件夹和其它文件夹
    • 代表着页面的名字，或者类名。
    • 由名词组成（例如：profile/）。
    • 如果有两个以上单词，采用 kebab-case 短横线 的风格（例如：error-page/）。

    例如：

    src/
├── App.vue
├── assets
├── main.js
├── components
│   ├── BackToTop             # 通用组件的文件夹
│   └── Charts                # 通用组件的文件夹
│       ├── Keyboard.vue
│       ├── LineMarker.vue
│       ├── MixChart.vue
│       └── mixins            # 其它文件夹（不是 components/ 的直接子文件夹）
├── directive
│   ├── clipboard             # 其它文件夹
│   └── permission            # 其它文件夹
├── filters
└── views
    ├── charts                # 视图组件的文件夹
    ├── clipboard             # 视图组件的文件夹
    ├── dashboard             # 视图组件的文件夹
    │   ├── admin             # 视图组件的文件夹
    │   │   ├── components
    │   │   └── index.vue
    │   ├── editor            # 视图组件的文件夹
    │   │   └── index.vue
    │   └── index.vue
    └── error-page            # 视图组件的文件夹
        ├── 401.vue
        └── 404.vue

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28

    1.3 Vue 组件命名

    1.3.1 单文件组件名

    文件扩展名为 .vue 的 single-file components（单文件组件）。单文件组件名应该始终是单词大写开头（PascalCase 大驼峰）。

    我们这里说的大驼峰命名的组件指的是components/文件夹下的可复用的公用组件（非页面组件）,也包括 views/视图文件夹下的私有 components/文件夹下的私有组件。但不包括 views/ 文件夹下的页面组件，页面视图组件采用kebab-case 的风格。

    推荐：

    src/
├── MyComponent.vue

    • 1
    • 2
    为什么选择大驼峰（PascalCase）作为components组件的命名格式？
    1. PascalCase 是合法的 JavaScript 标识符。这使得在 JavaScript 中导入和注册组件都很容易，同时 IDE 也能提供较好的自动补全。
    2. 在模板中更明显地表明了这是一个 Vue 组件，而不是原生 HTML 元素。同时也能够将 Vue 组件和自定义元素 (web components) 区分开来。

    在单文件组件和内联字符串模板中，我们都推荐这样做。但是，PascalCase 的标签名在 DOM 模板中是不可用的，详情参见 DOM 模板解析注意事项。

    为了方便，Vue 支持将模板中使用 kebab-case 的标签解析为使用 PascalCase 注册的组件。这意味着一个以 MyComponent 为名注册的组件，在模板中可以通过 或 引用。这让我们能够使用同样的 JavaScript 组件注册代码来配合不同来源的模板。

    1.3.2 单例组件名

    只拥有单个活跃实例的组件应该以 The 前缀命名，以示其唯一性。

    这不意味着组件只可用于一个单页面，而是_每个页面_只使用一次。这些组件永远不接受任何 prop，因为它们是为你的应用定制的。如果你发现有必要添加 prop，那就表明这实际上是一个可复用的组件，_只是目前_在每个页面里只使用一次。

    比如，头部和侧边栏组件几乎在每个页面都会使用，不接受 prop，该组件是专门为该应用所定制的。

    推荐：

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

    • 1
    • 2
    • 3

    不推荐：

    components/
├── Heading.vue
├── MySidebar.vue

    • 1
    • 2
    • 3
    1.3.3 基础组件名

    基础组件：不包含业务，独立、具体功能的基础组件，比如日期选择器、模态框等。这类组件作为项目的基础控件，会被大量使用，因此组件的 API
    进行过高强度的抽象，可以通过不同配置实现不同的功能。

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

    基础组件在一个页面内可使用多次，在不同页面内也可复用，是高可复用组件。

    推荐：

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

    • 1
    • 2
    • 3
    • 4

    不推荐：

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

    • 1
    • 2
    • 3
    • 4
    1.3.4 业务组件

    业务组件：它不像基础组件只包含某个功能，而是在业务中被多个页面复用的（具有可复用性），它与基础组件的区别是，业务组件只在当前项目中会用到，不具有通用性，而且会包含一些业务，比如数据请求；而基础组件不含业务，在任何项目中都可以使用，功能单一，比如一个具有数据校验功能的输入框。

    掺杂了复杂业务的组件（拥有自身 data、prop 的相关处理）即业务组件。应该以Custom前缀命名。

    业务组件在一个页面内比如：某个页面内有一个卡片列表，而样式和逻辑跟业务紧密相关的卡片就是业务组件。

    推荐：

    components/
|- custom-card.vue

    • 1
    • 2
    1.3.5 紧密耦合的组件名

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

    和父组件紧密耦合的子组件一般以父组件名作为前缀命名。

    推荐：

    components/
├── TodoList.vue
├── TodoListItem.vue
├── TodoListItemButton.vue


    • 1
    • 2
    • 3
    • 4
    • 5

    不推荐：

    components/
├── TodoList.vue
├── ItemForTodoList.vue
├── ButtonForTodoListItem.vue

    • 1
    • 2
    • 3
    • 4
    1.3.6 组件名中单词顺序

    组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。 因为编辑器通常会按字母顺序组织文件，所以现在组件之间的重要关系一目了然。

    这个表达比较抽象，下面以搜索和设置功能的组件为例，解释什么叫「高级别」。

    推荐：

    components/
├── SearchButtonClear.vue
├── SearchButtonRun.vue
├── SearchInputQuery.vue
├── SearchInputExcludeGlob.vue
├── SettingsCheckboxTerms.vue
├── SettingsCheckboxLaunchOnStartup.vue

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7

    不推荐：

    components/
├── ClearSearchButton.vue
├── ExcludeFromSearchInput.vue
├── LaunchOnStartupCheckbox.vue
├── RunSearchButton.vue
├── SearchInput.vue
├── TermsCheckbox.vue

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7

    还有另一种多级目录的方式，把所有的搜索组件放到 search/ 目录，把所有的设置组件放到 settings/ 目录。我们只推荐在非常大型（如有 100+ 个组件）的应用下才考虑这么做，因为在多级目录间找来找去，要比在单个 components 目录下滚动查找花费的精力更多。

    1.3.7 组件名必须是完整单词，禁用缩写

    组件名应该倾向于完整单词而不是缩写，这样便于团队合作与后期维护。编辑器中的自动补全已经让书写长命名的代价非常之低了，而其带来的明确性却是非常宝贵的。不常用的缩写尤其应该避免。

    推荐：

    components/
├── StudentDashboardSettings.vue
├── UserProfileOptions.vue

    • 1
    • 2
    • 3

    不推荐：

    components/
├── SdSettings.vue
├── UProfOpts.vue

    • 1
    • 2
    • 3
    1.3.8 页面组件名

    视图文件夹：位于 views/ 文件夹下，代表着一类页面的名字，存放视图组件。
    视图组件：代表着某一页面的名字，或者类名。
    视图组件与其它组件的区别是：视图组件位于 view/ 文件夹或视图文件夹下，其它组件位于 components/ 文件夹下。

    • 视图组件可以直接位于 views/ 文件夹下，例如：Login.vue、Home.vue。
    • 视图文件夹的名字要代表着页面的名字，例如：login/、error-page/。
    • 视图文件夹下只有一个视图组件的时候，该组件取名为 index.vue，例如：login/index.vue。
    • 视图文件夹下有两个以上视图组件的时候，分别取名，要体现内部文件的所属类名，例如：car/car-list.vue 和 car/car-detail.vue。
    • 尽量是名词。
    • 常用结尾单词有（detail、edit、list、info、report）。
    • 视图文件夹下可以存在私有 components/，其内部 .vue 文件遵循其它组件的命名方式（大驼峰）。
    • 除 components/ 下的，一律采用 kebab-case 的风格。

    例如：

    src/
├── components
│   ├── BackToTop               # 通用组件的文件夹
│   └── Charts                  # 通用组件的文件夹
│       ├── Keyboard.vue
│       ├── LineMarker.vue
│       ├── MixChart.vue
│       └── mixins              # 其它文件夹
└── views
    ├── login                   # 视图组件的文件夹
    │   └── index.vue
    ├── profile                 # 视图组件的文件夹
    │   ├── index.vue
    │   └── components
    ├── car                     # 视图组件的文件夹
    │   ├── car-list.vue        # 视图组件
    │   ├── car-detail.vue      # 视图组件
    │   └── components
    │       ├── CarListItem.vue
    │       └── CarInfoItem.vue
    └── error-page              # 视图组件的文件夹
        ├── 401.vue             # 视图组件
        └── 404.vue             # 视图组件

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23

    1.4 Vue 组件内部参数命名

    1.4.1 name

    组件名应该始终是多个单词，应该始终是 PascalCase 大驼峰命名。 根组件 App 以及 、 之类的 Vue 内置组件除外。这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。

    推荐：

    export default {
  name: 'ToDoList',
  // ...
}

    • 1
    • 2
    • 3
    • 4
    1.4.2 prop

    在声明 prop 的时候，其命名应该始终使用 camelCase小驼峰，而在模板和 JSX 中应该始终使用 kebab-case短横线。我们单纯的遵循每个语言的约定，在 JavaScript 中更自然的是 camelCase。而在 HTML 中则是 kebab-case。

    推荐：

    //template 模板中
<welcome-message greeting-text="hi"/>

    • 1
    • 2
    //