前端代码规范
关于注释问题
注释规遵循jsDoc
类注释(多行注释)
/**
* 工具类
* @author 丁少华
* @date 2020-01-01 08:00:00
*/
方法注释(多行注释)
/**
* 用于xxx
* @param {string} uid - 用户id
* @return {User} 一个用户
*/
属性注释(单行注释)
// 用户的id
let uid = '12345';
html注释
<!--region 选择框-->
<el-table-column type="selection"/>
<!--endregion-->
快捷键配置
如果嫌注释麻烦,网上有很多编辑器设置注释模板的配置
关于编码规范
行数
- 单个文件总行数不得超过600行
- vue的template不得超过300行
- 单个vue组件内,若样式超出100行,样式需独立出来
命名规范
- 代码中,除了js部分可以用驼峰命名外,其他均用中划线方式
- 代码中,js部分命名遵循常规命名规范,并命名要有意义,禁止用拼音和单字符做key
- 代码中,代码整齐,不要有多余的空格和行数,书写代码的时候就要注意
- 文件中,文件夹,文件(vue、js、less)均使用中划线命名方式
关于缩进
- 缩进均用两个space代替,禁止使用tab
关于ts
- 详细文档参考官方文档
- 属性,方法形参和返回值 都必须要有类型
- 在任何时候都不要有限考虑用any作为类型
vue和element ui
- 使用路由时,用路由名称(定义的枚举)来访问,方便以后维护
- 使用饿了么ui的表单,label可以添加label-suffix为label添加冒号
优秀的习惯
书写代码要思考
书写代码一定要想好,规划好再编写,切勿无脑从上到下机械的写下去。
如果工作内容成了一个体力活,那就要认真反思了
模块化
以下情况下,要考虑抽离组件或提取代码,切分模块
- 组件代码较长,且部分代码逻辑较为独立
- 有多个地方用到
其他
- ajax我会封装一个类,不能在组件内直接用aixos发请求,并须有层封装
- 团队步调要一致,如果有更好的方案,可以讨论决定,不得擅自改变规则
-------以下为公司原始文档------------
---分割线---
目前前端技术栈以Vue2.0为主,小程序开发主要以WePY为开发框架;所以规范主要以Vue为基础,主要包括JS、Css、文件命名、项目结构、注释
- 1技术栈
- 2项目结构
- 2.1整体结构
- 2.2views层结构规范
- 3文件命名
- 3.1文件夹命名、文件命名、组件命名
- 3.2函数、变量、常量、css类名、标签命名
- 3.2.1函数、变量
- 3.2.2常量
- 3.2.3css类名
- 3.2.4标签
- 3.3注释
- 3.3.1单行注释
- 3.3.2多行注释
- 3.3.3函数注释
- 3.3.4html块级注释
- 3.3.5文件自动生成注释头信息
- 4其它
- 4.1尽量使用缩写属性
- 4.2尽量使用缩写属性对于代码效率和可读性是很有用的
- 4.3零后面不带单位
- 4.4组件的 data 必须是一个函数
- 4.5Prop
- 4.6为 v-for 设置键值
- 4.7避免 v-if 和 v-for 用在一起
- 4.8为组件样式设置作用域
- 4.9使用 TODO 标注问题的解决方式
- 4.10vue文件中的指令缩写
- 4.11跨域
- 4.12状态管理
- 4.13调试
- 4.14浏览器适配
技术栈
vue全家桶、相关生态、ts/ES6、tslint/eslint、less、组件库:PC:element-ui,移动端:vant,
开发相关:WebStorm/VS code、git、pxcook(账号使用中文名)、Chrome/firefox
项目结构
这只是项目模板中的基础结构,具体需要结合项目需求进行定制化修改;以下项目结构基本上可以满足项目开发。
整体结构
- api:接口请求Api层
- assets:静态资源文件
- base:BLL业务逻辑层基类(构造函数)
- components:公共组件
- utils:工具箱帮助
- plugins:插件
- types:类型定义文件
- directives:自定义指令
- router:路由文件
- styles:公用样式
- views:组件
- store:vuex持久化
views层结构规范
views层是表现层,为了避免单个文件代码量过大的隐患,Vue组件采用 template、styles、js 分离的形式,外层采用业务文件夹命名的方式。结构清晰、单个文件的代码量较少、后期易于维护、特殊组件/文件置于业务文件夹。
分离规则:js>200行 与 css>100行 将js & css 单独抽出
-views
-home-page
index.vue
index.js
index.less
文件命名
文件夹命名、文件命名、组件命名
命名规则:kebab-case命名规范(短横线命名)
不能含有特殊字符、空格
文件名应该更倾向于完整单词而不是缩写
vue文件命名:统一使用小写字母开头的(kebab-case)命名规范;非vue文件(ts、js、css、less……)
组件必须包含 name 属性
全局通用的组件放在/src/components下
应该以一个特性的前缀开头,比如 v
组件名称 name: 使用大写字母开头的 PascalBase 风格
-src
-components
-v-table
index.vue
-v-svg-icon
index.vue
其它业务页面中的组件,放在个子页面下的 ./components文件夹下
-home-page
-components
pan-item.vue
index.vue
index.js
index.less
函数、变量、常量、css类名、标签命名
命名使用英文,不允许出现拼音、拼音首字母等命名,要求通俗易懂
函数、变量
命名规则:小驼峰
且变量定义方式必须使用 let,不允许使用 var
let tempName =function initData() {}
常量
命名规则:全部大写:使用大写字母和下划线组合命名,下划线用于分隔单词
此规则适用于位于文件顶部常量、独立的常量文件中的命名,如果是方法体内部的常量,应当使用小驼峰的命名规则
const CASE_ID = 'XXX'
css类名
命名规则:class为完整小写单词并以 - 连接
.form-input {font-size:14px;color:#333333;}
尽量不要使用内嵌式style
注:ID的权重高,一般情况下,不应用于样式;如果需要使用 ID 解决样式的优先级,ID的命名规则为:帕斯卡命名法
标签
非 Html 标签,比如:组件名(参照文件命名:kebab-case命名规范),则在template中,组件引用使用小写单词且用 - 连接
<template>
<i-table></i-table>
</template>
<script>
import iTable from '@/components/iTable/index.vue'
export default {
components: { ITable },
...
}
</script>
注释
项目中使用到的注释一般为:文件头注释、html块级注释、多行注释、单行注释、函数注释;且完整项目中的代码注释量不能少于代码总量的30%。
单行注释
单独一行:// (双斜杠)与注释内容之间保留一个空格
在代码后添加注释:// (双斜杠)与代码之间保留一个空格,同时与注释内容之间保留一个空格
let userName = '哈哈'; // 登录名
多行注释
以 /* 开头,以 */ 结尾,且与注释内容之间保留一个空格
/* this.tableCurrentPagination = {
pageIndex: 1,
pageSize: size
} */
函数注释
函数注释也是多行注释的一种
/**
* 取消收藏
*/
html块级注释:
可以将 html dom 按照功能块级折叠,方便阅读和维护
<!--region 选择框-->
<el-table-column v-if="options.mutiSelect" type="selection" style="width: 55px;">
</el-table-column>
<!--endregion-->
注:webstorm已经配置了注释模板,输入 re 点击 Tab即可
文件自动生成注释头信息
Js文件
/**
* @Author : ChangJun
* @Date : 2018/10/27
* @Version : 1.0
* @Content : 接口层
*/
Vue文件
<!--
* @Author : ChangJun
* @Date : 2018/12/13
* @Version : 1.0
* @Content :
-->
Css文件
/**
* @Author : ChangJun
* @Date : 2018/12/13
* @Version : 1.0
* @Content :
*/
注:webstorm设置中,添加自动生成注释头信息
其它
尽量使用缩写属性
尽量使用缩写属性对于代码效率和可读性是很有用的
正例:
border-top: 0;
padding: 0 1em 2em;
反例:
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
0 后面不带单位
正例:
padding-bottom: 0;
margin: 0;
反例:
padding-bottom: 0px;
margin: 0em;
组件的 data 必须是一个函数
当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方),它的值必须是返回一个对象的函数。
data () {
return {
pageIndex: 1,
tableCurrentPagination: {},
multipleSelection: [] // 多行选中
}
}
Prop
Prop定义应该尽量详细,必须指定其类型
props: {
total: {
type: Number,
default: 0
}, // 总数
pagination: {
type: Object,
default: null // 分页参数 === pageSize:每页展示的条数,pageIndex:当前页,pageArray: 每页展示条数的控制集合,默认 _page_array
}
}
为 v-for 设置键值
在组件上总是必须用 key 配合 v-for,以便维护内部组件及其子树的状态
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
避免 v-if 和 v-for 用在一起
永远不要把 v-if 和 v-for 同时用在同一个元素上
<ul v-if="shouldShowUsers">
<li v-for="user in users" :key="user.id">
{{ user.name }}
</li>
</ul>
为组件样式设置作用域
对于用于来说,顶级App组件和布局组件的样式可以是全局的,但是其它所有组件都应该是有作用域的。这条规则只和单文件组件有关。你不一定要使用 scoped 特性。
<template>
<button class="button button-close">X</button>
</template>
<!-- 使用 `scoped` 特性 -->
<style scoped>
.button {
border: none;
border-radius: 2px;
}
.button-close {
background-color: red;
}
</style>
使用 TODO 标注问题的解决方式
vue文件中的模块顺序
<template></template>
<script></script>
<style></style>
vue文件中的指令缩写
指令缩写 (用 : 表示 v-bind:
和用 @
表示 v-on:
)
跨域
跨域线下通过
proxytable
解决,线上通过运维配置Nginx代理
状态管理
如果需要缓存,使用vuex-persistedstate
调试
避免线上环境出现控制台输出、警告、报错等信息
推荐使用console.debug
浏览器适配
IE 8及以下不做考虑,使用polyfill
typescript
装饰器
参数要声明类型,尽量不要使用any
单组件类名与文件名保持一致