前端服务
前言:
前端服务一般包含:WEB 、H5、 IOS、 Android、 PC、小程序
未来保证团队里面的开发的整体代码风格一致,流程规范化,我们一定要把前端的规范好好遵守起来,在平时开发过程中就开始培养自己的开发习惯,而不是等项目上线了才开始优化风格,不然你就会相当痛苦,哪怕团队里面只有你自己一个前端。
1 - 文件命名规范
【推荐】html,css,js,lib,images文件均存放至项目的目录中。如果使用相关前端框架,根据框架的文件格式进行合理布局。
【强制】所有文件夹及文件使用英文命名(避免使用中文路径)。
【强制】html文件:入口文件使用index.html。如果有对应的设计组设计原稿,需要将对应的设计稿和html文件命名一致并合理存放。
【强制】css文件命名:后缀.css。通用initial.css,初始化base.css,首页index.css,其他页面按照对应的html命名。
【强制】Js文件命名:英文命名,后缀.js.通用common.js,初始化base.js。 其他页面按照对应的html命名。
2 - HTML规范
【推荐】文档类型声明及编码:统一为html5声明类型。书写时利用IDE实现层次分明的缩进(默认缩进4空格)。
【推荐】非特殊情况下CSS文件放在body部分标签后。非特殊情况下大部分JS文件放在标签尾部(如果需要界面未加载前执行的代码可以放在head标签后)避免行内JS和CSS代码。
【强制】所有编码需要遵循html(XML)标准,标签&属性&属性命名必须由小写字母及下划线数字组成,且所有标签必须闭合,包括br(),hr()等。属性值用双引号。
【推荐】引入JS库文件,文件名须包含库名称及版本号及是否为压缩版,比如jquery-1.4.1.min.js。引入插件,文件名格式为库名称+插件名称,比如jQuery.bootstrap.js。
【推荐】书写页面过程中,请考虑向后扩展性。class&id参见css书写规范.
【推荐】需要为html元素添加自定义属性的时候,首先要考虑下有没有默认的已有的合适标签去设置,如果没有,可以使用须以"data-"为前缀来添加自定义属性,避免使用"data:"等其他命名方式。
【推荐】语义化html,如标题根据重要性用h*(同一页面只能有一个h1),段落标记用p,列表用ul,内联元素中不可嵌套块级元素。
【推荐】尽可能减少div多层级嵌套。
【推荐】书写链接地址时,必须避免重定向,例如:href=“http://myVue.com/”,即须在URL地址后面加上“/”;
【推荐】在页面中尽量避免使用style属性,即style=“…”。
【推荐】必须为含有描述性表单元素(input,textarea)添加label,如姓名:须写成:姓名:
【推荐】能以背景形式呈现的图片,尽量写入css样式中。
【推荐】重要图片必须加上alt属性。给重要的元素和截断的元素加上title。
【推荐】给区块代码及重要功能(比如循环)加上注释,方便后台添加功能。
【推荐】特殊符号使用:尽可能使用代码替代:比如<(<)&>(>)&空格()&»(»)等等。
3 - JS规范
【强制】文件编码统一为utf-8,书写过程过,每行代码结束必须有分号。原则上所有功能均根据XXX项目需求原生开发,以避免网上down下来的代码造成的代码污染(沉冗代码||与现有代码冲突||…)。
【推荐】库引入:原则上仅引入jQuery库,若需引入第三方库,须与团队其他人员讨论决定。
【强制】变量命名:驼峰式命名.原生JS变量要求是纯英文字母,首字母须小写,如myVue。jQuery变量要求首字符为’_',其他与原生JS规则相同,如:_myVue。另,要求变量集中声明,避免全局变量.
【强制】类命名:首字母大写,驼峰式命名.如MyVue。
【强制】函数命名:首字母小写驼峰式命名.如myVue()。
【推荐】命名语义化,尽可能利用英文单词或其缩写。
函数常用的方法名:
get 获取 / set 设置,
add 增加 / remove 删除
create 创建 / destory 移除
start 启动 / stop 停止
open 打开 / close 关闭,
read 读取 / write 写入
load 载入 / save 保存,
create 创建 / destroy 销毁
begin 开始 / end 结束,
backup 备份 / restore 恢复
import 导入 / export 导出,
split 分割 / merge 合并
inject 注入 / extract 提取,
attach 附着 / detach 脱离
bind 绑定 / separate 分离,
view 查看 / browse 浏览
edit 编辑 / modify 修改,
select 选取 / mark 标记
copy 复制 / paste 粘贴,
undo 撤销 / redo 重做
insert 插入 / delete 移除,
add 加入 / append 添加
clean 清理 / clear 清除,
index 索引 / sort 排序
find 查找 / search 搜索,
increase 增加 / decrease 减少
play 播放 / pause 暂停,
launch 启动 / run 运行
compile 编译 / execute 执行,
debug 调试 / trace 跟踪
observe 观察 / listen 监听,
build 构建 / publish 发布
input 输入 / output 输出,
encode 编码 / decode 解码
encrypt 加密 / decrypt 解密,
compress 压缩 / decompress 解压缩
pack 打包 / unpack 解包,
parse 解析 / emit 生成
connect 连接 / disconnect 断开,
send 发送 / receive 接收
download 下载 / upload 上传,
refresh 刷新 / synchronize 同步
update 更新 / revert 复原,
lock 锁定 / unlock 解锁
check out 签出 / check in 签入,
submit 提交 / commit 交付
push 推 / pull 拉,
expand 展开 / collapse 折叠
begin 起始 / end 结束,
start 开始 / finish 完成
enter 进入 / exit 退出,
abort 放弃 / quit 离开
obsolete 废弃 / depreciate 废旧
【推荐】尽量避免使用存在兼容性及消耗资源的方法或属性,比如eval_r()&innerText。
【推荐】后期优化中,JS非注释类中文字符须转换成unicode编码使用,以避免编码错误时乱码显示。
【推荐】代码结构明了,加适量注释.提高函数重用率。
【推荐】注重与html分离,减小reflow,注重浏览器性能.
【推荐】字符串统一使用单引号(‘),不使用双引号(“)。这在创建 HTML 字符串非常有好处
【推荐】使用字面值创建对象
正例: let user = {};
反例: let user = new Object();
【推荐】永远不要直接使用 undefined 进行变量判断;使用 typeof 和字符串’undefined’对变量进行判断。
【推荐】this 的转换命名:对上下文 this 的引用只能使用’self’来命名
【推荐】慎用console.log,console.log 大量使用会有性能问题,所以在非webpack 项目中谨慎使用log 功能
4 - Vue 项目规范
vue 项目规范以 Vue 官方规范 (https://cn.vuejs.org/v2/style-guide/) 中的 A 规范为基础,在其上面进行项目开发,故所有代码均遵守该规范。
请仔仔细细阅读 Vue 官方规范,切记,此为第一步。
5 - 组件规范
【强制】组件名为多个单词。
组件名应该始终是多个单词组成(大于等于 2),且命名规范为KebabCase格式。
这样做可以避免跟现有的以及未来的 HTML 元素相冲突,因为所有的 HTML 元素名称都是单个单词的。
正例:
export default {
name: 'TodoItem'
// ...
};
反例:
export default {
name: 'Todo',
// ...
}
export default {
name: 'todo-item',
// ...
}
【强制】组件文件名为 pascal-case 格式
正例:
components/
|- my-component.vue
反例:
components/
|- myComponent.vue
|- MyComponent.vue
【推荐】和父组件紧密耦合的子组件应该以父组件名作为前缀命名
正例:
components/
|- todo-list.vue
|- todo-list-item.vue
|- todo-list-item-button.vue
|- user-profile-options.vue (完整单词)
反例:
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
|- UProfOpts.vue (使用了缩写)
【推荐】在 Template 模版中使用组件,应使用 PascalCase 模式,并且使用自闭合组件。
正例:
<!-- 在单文件组件、字符串模板和 JSX 中 -->
<MyComponent />
<Row><table :column="data"/></Row>
反例:
<my-component /> <row><table :column="data"/></row>
【强制】组件的 data 必须是一个函数
当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方),它的值必须是返回一个对象的函数。 因为如果直接是一个对象的话,子组件之间的属性值会互相影响。
正例:
export default {
data () {
return {
name: 'jack'
}
}
}
反例:
export default {
data: {
name: 'jack'
}
}
【推荐】Props 定义应该尽量详细
必须使用 camelCase 驼峰命名
必须指定类型
必须加上注释,表明其含义
必须加上 required 或者 default,两者二选其一
如果有业务需要,必须加上 validator 验证
正例:
props: {
// 组件状态,用于控制组件的颜色
status: {
type: String,
required: true,
validator: function (value) {
return [
'succ',
'info',
'error'
].indexOf(value) !== -1
}
},
// 用户级别,用于显示皇冠个数
userLevel:{
type: String,
required: true
}
}
【推荐】为组件样式设置作用域
正例:
<template>
<button class="btn btn-close">X</button>
</template>
<!-- 使用 `scoped` 特性 -->
<style scoped>
.btn-close {
background-color: red;
}
</style>
反例:
<template>
<button class="btn btn-close">X</button>
</template>
<!-- 没有使用 `scoped` 特性 -->
<style>
.btn-close {
background-color: red;
}
</style>
【推荐】如果特性元素较多,应该主动换行。
正例:
<MyComponent foo="a" bar="b" baz="c"
foo="a" bar="b" baz="c"
foo="a" bar="b" baz="c"
/>
反例:
<MyComponent foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c"/>
【推荐】模板中使用简单的表达式
组件模板应该只包含简单的表达式,复杂的表达式则应该重构为计算属性或方法。复杂表达式会让你的模板变得不那么声明式。我们应该尽量描述应该出现的是什么,而非如何计算那个值。而且计算属性和方法使得代码可以重用。
正例:
<template>
<p>{{ normalizedFullName }}</p>
</template>
// 复杂表达式已经移入一个计算属性
computed: {
normalizedFullName: function () {
return this.fullName.split(' ').map(function (word) {
return word[0].toUpperCase() + word.slice(1)
}).join(' ')
}
}
反例:
<template>
<p>
{{
fullName.split(' ').map(function (word) {
return word[0].toUpperCase() + word.slice(1)
}).join(' ')
}}
</p>
</template>
【强制】指令都使用缩写形式
指令推荐都使用缩写形式,(用 : 表示 v-bind: 、用 @ 表示 v-on: 和用 # 表示 v-slot:)
正例:
<input
@input="onInput"
@focus="onFocus"
>
反例:
<input
v-on:input="onInput"
@focus="onFocus"
>
【推荐】标签顺序保持一致
单文件组件应该总是让标签顺序保持为 `
【强制】必须为 v-for 设置键值 key
【推荐】v-show 与 v-if 选择
如果运行时,需要非常频繁地切换,使用 v-show ;如果在运行时,条件很少改变,使用 v-if。
【推荐】script 标签内部结构顺序
components > props > data > computed > watch > filter > 钩子函数(钩子函数按其执行顺序) > methods
6 - Vue Router 规范
【推荐】页面跳转数据传递使用路由参数
页面跳转,例如 A 页面跳转到 B 页面,需要将 A 页面的数据传递到 B 页面,推荐使用 路由参数进行传参,而不是将需要传递的数据保存 vuex,然后在 B 页面取出 vuex 的数据,因为如果在 B 页面刷新会导致 vuex 数据丢失,导致 B 页面无法正常显示数据。
正例:
let id = ' 123';
this.$router.push({ name: 'userCenter', query: { id: id } });
【推荐】使用路由懒加载(延迟加载)机制
{
path: '/uploadAttachment',
name: 'uploadAttachment',
meta: {
title: '上传附件'
},
component: () => import('@/view/components/uploadAttachment/index.vue')
}
【推荐】path、childrenPoints 命名规范采用kebab-case命名规范(尽量vue文件的目录结构保持一致,因为目录、文件名都是kebab-case,这样很方便找到对应的文件)
【推荐】name 命名规范采用KebabCase命名规范且和component组件名保持一致!(因为要保持keep-alive特性,keep-alive按照component的name进行缓存,所以两者必须高度保持一致)
// 动态加载
export const reload = [
{
path: '/reload',
name: 'reload',
component: Main,
meta: {
title: '动态加载',
icon: 'icon iconfont'
},
children: [
{
path: '/reload/smart-reload-list',
name: 'SmartReloadList',
meta: {
title: 'SmartReload',
childrenPoints: [
{
title: '查询',
name: 'smart-reload-search'
},
{
title: '执行reload',
name: 'smart-reload-update'
},
{
title: '查看执行结果',
name: 'smart-reload-result'
}
]
},
component: () =>
import('@/views/reload/smart-reload/smart-reload-list.vue')
}
]
}
];
【推荐】path除了采用kebab-case命名规范以外,必须以 / 开头,即使是children里的path也要以 / 开头。如下示例
7 - Vue 项目目录规范
【推荐】vue 项目中的所有命名一定要与后端命名统一。
比如权限:后端 privilege, 前端无论 router , store, api 等都必须使用 privielege 单词!
【推荐】使用 vue-cli3 来初始化项目,项目名按照上面的命名规范。
目录名按照上面的命名规范,其中 components 组件用大写驼峰,其余除 components 组件目录外的所有目录均使用 kebab-case 命名。
src 源码目录
|-- api 所有api接口
|-- assets 静态资源,images, icons, styles等
|-- components 公用组件
|-- config 配置信息
|-- constants 常量信息,项目所有Enum, 全局常量等
|-- directives 自定义指令
|-- filters 过滤器,全局工具
|-- datas 模拟数据,临时存放
|-- lib 外部引用的插件存放及修改文件
|-- mock 模拟接口,临时存放
|-- plugins 插件,全局使用
|-- router 路由,统一管理
|-- store vuex, 统一管理
|-- themes 自定义样式主题
|-- views 视图目录
| |-- role role模块名
| |-- |-- role-list.vue role列表页面
| |-- |-- role-add.vue role新建页面
| |-- |-- role-update.vue role更新页面
| |-- |-- index.less role模块样式
| |-- |-- components role模块通用组件文件夹
| |-- employee employee模块
最后
If builders built buildings the way programmers write programs, then
the first woodpecker that came along would destroy civilization.
(如果建筑师盖房子就像程序员写程序一样,那么,第一只到来的啄木鸟就能毁掉我们的文明)