前端开发指引 -- VUE篇
一、编写目的
为提高团队协作效率, 便于后台人员添加功能, 及前端后期优化维护, 输出高质量的代码及文档是至关重要的。
二、环境要求
【强制】使用 Visual Studio Code (VS Code) 进行代码编写。
【强制】代码提交前使用 VS Code 进行格式化（不要引入外部的格式化文件）。
-
【强制】规定 Tab 大小为 4 个空格，保证在所有环境下获得一致展现。
settings.json { "editor.tabSize": 4 ... } 【推荐】安装插件
Vetur（Vue开发扩展 及Vue文件代码格式化）。【推荐】安装插件 Prettier - Code formatter（
CSS/ Less /JS等其他文件代码格式化；Vetur的格式化基于此插件实现，固可以在所有文件实现统一的格式化）。【推荐】安装插件 Chinese (Simplified) Language Pack for Visual Studio Code （ VS Code 简体中文语言包）。
【推荐】使用 Chrome 浏览器并安装
Vue.js devtools进行调试。
三、命名要求
3.1 普通变量命名
命名方法 ：小驼峰命名法
-
命名要求 ：
-
命名必须与需求内容相关，若想声明为变量，如：“我的业务”，需采用如下定义方式：
let myBusiness = "我的业务"; -
命名为复数时, 若想声明为数组，如：很多人的名字，可采用如下的定义方式：
let names = [];
-
3.2 常量命名
命名方法 : 全部大写
-
命名要求 : 使用大写字母和下划线来组合命名，下划线用以分割单词。
const MAX_COUNT = 10; const URL = 'https://www.baidu.com/';
3.3 组件命名
官方文档推荐及使用遵循规则：
PascalCase(单词首字母大写命名)是最通用的声明约定。-
kebab-case (短横线分隔命名) 是最通用的使用约定。
组件名应该始终是多个单词的，根组件
App除外;有意义的名词、简短、具有可读性；
-
命名遵循
PascalCase约定:- 公用组件以
Abcd(公司名缩写简称) 开头，如:AbcdDatePicker,AbcdTable; - 页面内部组件以组件模块名简写为开头，Item 为结尾，如:
StaffBenchToChargeItem，StaffBenchAppNotArrItem。
- 公用组件以
-
使用遵循 kebab-case 约定：
- 在页面中使用组件需要前后闭合，并以短线分隔，如：
，
- 在页面中使用组件需要前后闭合，并以短线分隔，如：
导入及注册组件时，遵循
PascalCase约定；同时还需注意：必须符合自定义元素，切勿使用保留字。
3.4 methods 方法命名
- 小驼峰式命名，统一使用动词或者动词 + 名词形式。如:
badgo、nextPage、show、open、login goodjumpPage、openCarInfoDialog。 - 请求数据方法，以 data 结尾。如：
badtakeData、confirmData、getList、postForm goodgetListData、postFormData。 -
init、refresh单词除外。 - 尽量使用常用单词开头, 如：set、get、go、can、has、is。
3.5 views下的文件命名
只有一个文件的情况下不会出现文件夹，而是直接放在 views 目录下面，如:
index.vue。尽量是名词,且使用驼峰命名法。
开头的单词就是所属模块名字, 如：
workbenchIndex、workbenchList、workbenchEdit。-
名字至少两个单词。
- 反例：
workbench - 正例：
workbenchIndex
- 反例：
3.6 props命名
在声明 prop 时，命名应始终使用 camelCase，而在模板中应该始终使用 kebab-case。
-
反例：
-
正例：
3.7 例外情况
- 临时变量可以简写，如：
str，num，bol，obj，fun，arr。 - 循环变量可以简写，如：i，j，k 。
四、结构化
4.1 目录文件夹及子文件
|— build 构建脚本目录
|— build.js 生产环境构建（编译打包）脚本
|— check-versions.js 版本验证工具
|— utils.js 构建相关工具方法（主要用来处理css类文件的loader）
|— vue-loader.conf.js 处理vue中的样式
|— webpack.base.conf.js webpack基础配置
|— webpack.dev.conf.js webpack开发环境配置
|— webapck.prod.conf.js webpack生产环境配置
|— config 项目配置
|— dev.env.js 开发环境变量
|— index.js 主配置文件
|— prod.env.js 生产环境变量
|— test.env.js 测试环境变量
|— node_modules 项目依赖模块
|— mock mock数据目录，用于本地数据模拟
|— src 项目源码目录
|— assets 资源目录，资源会被webpack构建
|— js 公共js文件目录
|— css 公共样式文件目录
|— images 图片存放目录
|— components 公共组件目录
|— common
|— network 存放项目的网络模块，接口
|— tools 自己封装的一些工具
|— App.vue 根组件
|— main.js 入口js文件
|— routers 前端路由目录
|— index.js
|— pages 前端页面文件
|— store 应用级数据管理
|— index.js 组装模块并导出，统一管理导出，也可命名为store.js
|— state.js 单一状态树，定义应用数据结构及初始化状态
|— getters.js 获取state中的状态，仅单向获取数据，不做任何修改
|— actions.js 调用mutation方法对数据进行操作
|— mutation-types.js 存放vuex常用的变量
|— mutations.js 定义state数据的修改操作
|— static 纯静态资源，不会被webpack构建，eg:没有npm包模块
|— test 测试
|— unit 单元测试
|— e2e e2e测试
|— .babelrc babel的配置文件
|— .editorconfig 编辑器的配置文件
|— .gitignore git的忽略配置文件
|— .postcssrc.js postcss的配置文件
|— index.html html模板，入口页面
|— package.json npm包配置文件，依赖包信息
|— README.md 项目介绍
4.2 Vue文件基本结构
4.3 多个特性的元素
多个特性的元素应该分多行撰写，每个特性一行。(增强更易读)
4.4 元素特性的顺序
原生属性放前面，指令放后面。如下表所示：
- class
- id,ref
- name
- data-*
- src, for, type, href,value,max-length,max,min,pattern
- title, alt，placeholder
- aria-*, role
- required,readonly,disabled
- is
- v-for
- key
- v-if
- v-else-if
- v-else
- v-show
- v-cloak
- v-pre
- v-once
- v-model
- v-bind,:
- v-on,@
- v-html
- v-text
4.5 组件选项顺序
如下表所示：
- name
- components
- props
- data
- computed
- created
- mounted
- methods
- filter
- watch
五、 UI框架选择
- PC端Vue项目UI框架优先选择：Element UI、iView
- 移动端Vue项目UI框架：mint-ui（优先）
六、CSS预处理器选择
- Stylus
- 选择原因：Stylus是来源于Node.js社区，与js关系密切，富于表现力、动态的、健壮的 CSS、支持省略花括号、支持省略分号，灵活、整洁。
七、文件格式
UTF-8格式
八、Script
在 script标签中，你应该遵守 Js的规范和ES6规范。
- 组件名称：必须以大写字母开头驼峰法命名。
- Data必须是一个函数。
- Props定义：提供默认值，使用type属性校验类型，使用props之前先检查prop是否存在
- 调试信息 console.log() debugger使用完及时删除。
- 为v-for设置Key值。
- 使用计算 规避v-if和v-for用在一起。
- 无特殊情况不允许使用原生API操作dom,谨慎使用this.$refs直接操作dom。
- 使用ES6风格编码源码,定义变量使用let,定义常量使用const,使用
export,import模块化。 - 指令缩写：都用指令缩写 (用 : 表示 v-bind: 和用 @ 表示 v-on:)。
- 使用 data 里的变量时请先在 data 里面初始化。
- 函数中统一使用_this=this来解决全局指向问题。
- 能用单引号不用双引号。
- 尽量使用===。
- 声明变量必须赋值。
九、Style
- 使用 scoped关键字，约束样式生效的范围。
- 避免使用标签选择器（效率低、损耗性能）。
- 非特殊情况下，禁止使用 ID 选择器定义样式。有 JS 逻辑的情况除外。
- CSS 属性书写顺序：先决定定位宽高显示大小，再做局部细节修饰！推荐顺序：定位属性(或显示属性，display)->宽高属性->边距属性(margin, padding)->字体，背景，颜色等，修饰属性的定义。
十、资源路径的配置、引入规则
- 路径配置
在build/webpack.base.conf.js文件中配置。
alias: {
'@': resolve('src'), // 默认配置，设置src目录别名
'childRouter': resolve('src/pages/menuRouter'), // 子路由路径配置
'#': resolve('src/assets') // 配置assets文件夹路径
}
- 路径导入
Js文件中导入实例：
- 导入node_modules模块中的文件，直接引入即可，不需要加文件后缀名。
- 导入自定义文件的时候，使用相对路径或者使用路径配置别名，不许要加文件后缀名。
- 导入node_modules模块：import Vue from ‘vue’
- 导入自定义文件：
import router from "./router"
import scrollConfig from "#/js/vuescroll.config"
css或者stylus样式导入需要使用 ~@ 开头
@import '~common/stylus/variable'
十一、数据中心
- 各个文件的命名根据上面的项目结构命名。
- 应用层级的状态应该集中到单个 store 对象中。
- action和mutation中的函数统一声明在mutation-type.js内。
- mutation-types里面的常量、常量值全部用大写+英文单词配合下划线的形式：例如：export const UPDATE_USERINFO = “UPDATE_USERINFO”。
- 提交 mutation 是更改状态的唯一方法，并且这个过程是同步的。
- 异步逻辑都应该封装到 action 里面。
- vuex 的dispatch和commit提交mutation的区别：dispatch=>actions用来触发异步操作，commit=>mutation用来触发同步操作的方法。当操作行为中含有异步操作，比如向后台发送请求获取数据，就需要使用action的dispatch去完成，其他使用commit即可。
十二、路由
- 路由至少包含三个选项：path、name、component。path统一小写；name对应于组件中的name，大写开头驼峰；component组件名称大写开头的组件驼峰。
- 一级路由统一使用相对路径的形式。二级路由可以配置，配置见资源路径的配置、引入规则。
十三、axios
- 根据需要配置post、get请求，一个是取一个是贴，只需要读取文件，put（PUT 往服务器上上传文件）、delect（删除）直接对数据进行操作相对不安全 。
- axios的挂载：Vue.prototype.$http = axios;
- axios使用封装后的get/post请求。
- ajax的判断：
首先 ajax 请求可以写在 actions也可以直接写在 .vue 页面里。我们判断的依据是回调是否需要调用页面结构来区分,比如在.vue页面中发送完请求后需要调用 this.$refs.element等,或者需要利用组件的独立性的效果时 后，那就写在.vue页面,否则就写在 actions 里。
十四 、api管理
- 新建
src/ network/api.js
放置api路径，要注意 axios已经有了前缀,所以这里的 api 值需要写前缀之后的路径。当路径较多时可以再多建几个文件,分类放置。
例如：
// 统一管理接口
export default {
manage: {
fertilizerStation: '/api/AllFertSiteNameList', // 获取列表
userLogin: '/api/Login' // 用户登录
}
}
- 挂载
在main.js中引入：import api from "./request/api"。
使用Vue.prototype.api = api挂载到原型链上即可处处使用。
十五、依赖规范
- 在
package.json里增加包依赖
“dependencies”: {
"axios": "^0.18.0"
}
十六、 Web字体规范
- 优先使用框架中的字体图标，比如element ui中的
- 使用iconfont字体图标代替图片
- 在规范中包括的字体格式有：
woff: WOFF (Web Open Font 格式)
ttf: TrueType
ttf, otf: OpenType
eot: 嵌入式 OpenType
svg, svgz: SVG 字体
- 字体规则:
a) 为了防止文件合并及编码转换时造成问题，建议将样式中文字体名字改成对应的英文名字，如：黑体(SimHei)、宋体(SimSun)、微软雅黑(Microsoft Yahei)。
b) 字体粗细采用具体数值，粗体bold写成700，正常normal写成400。
c) font-size必须以px为单位。
为了对font-family取值进行统一，更好的支持各个操作系统上各个浏览器的兼容性，font-family不允许在业务代码中随意设置。
十七、注释
代码注释在一个项目的后期维护中显的尤为重要，所以我们要为每一个被复用的组件编写组件使用说明，为组件中每一个方法编写方法说明。
下列情况务必添加注释，具体列表如下：
- 公共组件使用说明；
- 各组件中重要函数或者类说明；
- 复杂的业务逻辑处理说明；
- 特殊情况的代码处理说明；对于代码中特殊用途的变量、存在临界值、函数中使用的 hack、使用了某种算法或思路等需要进行注释描述；
- 多重 if 判断语句；
- 注释块必须以 /（至少两个星号）开头/；
- 单行注释使用 //。
17.1 单行注释
注释单独一行，不要在代码后的同一行内加注释。例如：
// 反例：
var name =”abc”; // 姓名
// 正例：
// 姓名
var name = “abc”;
17.2 多行注释
如下表示例：
组件使用说明，和调用说明
/**
* 组件名称
* @module 组件存放位置
* @desc 组件描述
* @author 组件作者
* @date 2017年12月05日17:22:43
* @param {Object} [title] - 参数说明
* @param {String} [columns] - 参数说明
* @example 调用示例
*