Vue 开发规范

JeremyJone ... 2022-9-9 大约 7 分钟

# Vue 开发规范

作者:jeremyjone

版本:v1


本规范适用于所有基于 Vue 框架的开发。

开发工具,推荐使用 VS Code,或者 WebStorm

使用 VS Code 的话,需要安装 eslintHTML CSS SupportHTML SnippetsLive ServerVeturVue VSCode Snippets 等插件以实现更快、更好的开发。

# 1 命名规范

所有的命名应该具有明显的具象含义,尽可能的使用名词,不使用动词。

# 1.1 项目命名

采用全部小写的方式,并以下划线为分隔符。

new_test_project;
1

# 1.2 目录命名

目录命名应遵循以下规则:

  • 全部小写
  • 使用具有显式意义的词语
  • 如果是集合类别的,应当使用复数形式
  • 应该尽可能使用一个单词,如果需要多个,使用下划线连接
assets;
utils;
data_models;
1
2
3

# 1.3 文件命名

Vue 的文件应该从名称上区分组件的类型,它们可能是单一的组件,也可能是视图级别,甚至布局级别。应该以它们的功能结尾,分别使用 ComponentItemViewPageLayout 等。

组件类型文件的命名应该使用大驼峰的写法。

IconComponent.vue;
IconItem.vue;

HomeView.vue;
HomePage.vue;

GlobalLayout.vue;
1
2
3
4
5
6
7

提示

组件功能有很多,不一定只可以使用 Component,也可以显式的使用例如 ButtonToast 等,这时可以与组件的 name 一致。参看 组件的 name 属性

有一个特例,如果当前视图文件夹下只有一个文件,则应当使用index.vue作为文件名。

|—— user_page
|      |—— index.vue

// 引用时直接引用到目录即可
import("../user_page/");
// or
import UserPage from "../user_page";
1
2
3
4
5
6
7

提示

使用 index.vue 这个特例时,注意文件夹的名称需要具有显式意义。

# 1.4 组件的 name 属性

每一个组件都应该具有一个单独的名称,并且组件名必须是多个单词组成的,这是为了避免和 HTML 本身元素相冲突。

# 1.4.1 组件名的创建

为了更好地使用名称,作为组件名称的起始,应当是这个项目的全称或缩写。

export default {
  name: "JzIconItem"
  // ...
};
1
2
3
4

# 1.4.2 基础组件名

有一些组件应该是基础的,它适用于很多地方。这时,该组件名应当具有一个比较通用的名称。

BaseButton.vue;
1
export default {
  name: "JzBaseButton"
};
1
2
3

# 1.4.3 父子组件名

有一些紧密耦合的组件,这时子组件应当继承父组件名作为前缀。

DataList.vue;
DataListItem.vue;
DataListItemIcon.vue;
1
2
3

# 1.4.4 组件名的使用

在使用时,需要使用小写+连接字符“-”的形式。

import IconItem from "../IconItem.vue";
Vue.component("jz-icon-item", IconItem);
1
2

但是并不推荐直接这样使用,因为每一个组件都应该具有一个 name 属性,这是 组件名的创建 的规范,所以更推荐如下使用方式:



 



 


import IconItem from "../IconItem.vue";
// 全局注册
Vue.component(IconItem.name, IconItem);

// 局部注册
component{
  [IconItem.name]: IconItem
}
1
2
3
4
5
6
7
8

# 2 Prop 属性

定义 Prop 时,始终应该以小驼峰方式命名。而在组件传值时,使用小写+连接符“-”的方式。这是遵循语言特性,保持良好的代码风格。

同时,应当尽可能详细的为每一个 Prop 属性进行良好的类型说明,同时给出默认值并验证。

定义:

props: {
    itemId: {
        type: Number,
        required: true
    },
    itemName: {
        type: String,
        validator: function(v) {
            return v !== ""
        }
    },
    itemProps: {
        type: Object,
        // 需要注意,对象的默认值应该是一个工厂函数返回的
        default: function() {
            return {
                uri: "xxx/xxx/.."
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

使用:

<project-item :item-id="1" item-name="projectName"></project-item>
1

# 3 Vue 指令的使用

Vue 指令的使用,应当严格按照 Vue 的官方文档的介绍,比如v-for中,必须使用key

# 4 *.vue 文件的格式

vue 文件定义了每一个组件、视图或者布局内容,方便开发。使用 vue 文件,可能需要配置对应的 vue-loader,使用 vue-cli 创建项目可以更方便的开发。

提示

对于 vs code 用户,可以添加 VeturVue 2 SnippetsPrettier 等插件帮助快速开发。

*.vue文件是 Vue 的模板文件,它应当具有三个顶级标签:

<template>
  <div></div>
</template>

<script>
export default {
  // content
};
</script>

<style scoped></style>
1
2
3
4
5
6
7
8
9
10
11

对于 ts 用户,它应当为:

<template>
  <div></div>
</template>

<script lang="ts">
import { Component, Vue } from "vue-property-decorator";

@Component
export default class ClassName extends Vue {
  // content
}
</script>

<style lang="stylus" scoped></style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

这个样式是一种规范,虽然它并不是强制的,但我们在编写*.vue文件时仍然必须按照此格式和标签顺序。

# 4.1 template 的内容

template 标签中的内容是 html 部分,它应当包含且只包含一个顶级元素。

警告

顶级元素中不可以使用 v-for 这样的属性。

# 4.2 script 内容格式

每一个*.vue文件都是一个组件,它具有自己的生命周期和属性方法等,这些都在<script>标签中完成。标签内容应当按照下面的顺序进行开发。

同时,每一个属性之间都应当有一个空行。

<script>
export default {
  name: "Item",

  props: {},

  //... 生命周期函数
  created() {},

  mounted() {},

  destroyed() {},
  // ...

  inject: [],

  provide: {},

  mixins: [],

  data() {return {}},

  computed: {}

  watch: {}

  directives: {}

  filters: {}

  methods: {}

  components: {}

  // 如果使用
  render(h){}
};
</script>
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
29
30
31
32
33
34
35
36
37
38

如果属性为空,则可以不用填写,但总体的顺序应当是上述的顺序。

提示

这个顺序不是必须的,但它至少应当在同一项目中是保持一致的。

# 2 JavaScript 规范

所有 JavaScript 内容都应当基于 JavaScript 开发规范

# JSX

Vue 支持使用 JSX 进行开发,它使用在 render(h) 函数中。应当遵循以下原则:

  • 参数 createElement 的缩写为 h,这是官方文档约定的。
  • 尽可能使用 h("div", {}, []) 的方式创建元素。如果需要使用 JSX,需要书写工整,缩进整齐。

# 3 CSS 规范

所有 CSS 内容都应当基于 CSS 开发规范

*.vue文件中的 css,应当是具有作用域属性的。

同时,所有 css 属性也必须使用扩展的嵌套规则,推荐使用scsssassstylus等扩展的 css 语言。最好使用stylus

<style lang="stylus" scoped></style>
1

# 3.1 使用 CSS 文件注入

一种更好的方式,是单独写 CSS 文件。

CSS 文件应当符合小写+“_”下划线的命名规范。

CSS 文件应当放在styles文件夹下,然后在以导入的方式进行注入:

import "@/styles/user_page.styl";
1

提示

对于那些功能文件夹下只有 index.vue 的组件来说,对应的 css 文件可以放在同级目录下。

icon_item
  |-- index.vue
  └-- index.styl
1
2
3

# 4 注释

所有注释都应当遵循 JsDoc 的规范填写。

  • 每一个模块、类、函数,都应该有一个区块注释。
  • 每一个关键操作方法,都应该有一个单行/多行注释。
  • 注释不应当与代码在同一行。

 
 
 
 
 


 

// right
/**
 * 多行注释
 */

// 单行注释

// wrong
var age = 18; // 年龄
1
2
3
4
5
6
7
8
9

# 4.1 模块注释

每一个模块,应当是一个单独的文件,它应当包含某一类的多个方法。需要在头部注释内写清当前模块作用域哪些内容,具有哪些内容,如何使用,编写时间,编写人,版本等信息。

/**
 * @fileOverview: 模块功能是:xxx
 * @author: jeremyjone
 * @date: 2020/03/25
 * @version: 1.0.0
1
2
3
4
5

# 4.2 类注释/方法注释

每一个类/方法,都应当包含一个注释,写明当前类/方法所具有的功能和属性等。

/**
 * @constructor Person
 * @description 一个Person类
 * @example new Person("Jeremy", 23);
 * @param {String} username 姓名
 * @param {Number} age 年龄
 */
class Person {
  constructor(username, age) {
    this.username = username;
    this.age = age;
  }
}

/**
 * @description 加法运算
 * @param {Number} num1 加数
 * @param {Number} num2 被加数
 * @return {Number} 结果
 */
function add(num1, num2) {
  return num1 + num2;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23