web前端开发规范、HTML规范、JavaScript规范、style规范

前言
- 目的
HTML规范
- 用法规范
- 注释规范
CSS规范
- 用法规范
- 书写顺序
- 样式覆盖
- 注释规范
JavaScript规范
- 用法规范
- 组件选项
- 注释规范
命名规范
- 目录命名
- 图片命名
- 文件命名
- 方法命名
- 样式命名
- 常用词
工程结构
- 目录构建
- 代码风格
Git规范
- 分支说明
- 使用说明
相关连接

前言

目的

规范的目的是为了编写高质量的代码，提高代码质量和可读性，增强团队协作开发效率，统一编码风格。
文档说明
本文旨在统一团队前端代码规范，参考腾讯、百度、字节跳动等前端规范，结合团队日常业务需求以及团队日常开发过程中的总结而制定，如果发现错误敬请指正

HTML规范

用法规范

1、语义化标签

标签语义化，切忌清一色的div元素。列表可以使用ul标签和li标签，文字使用p标签，标题使用h*标签等。HTML5推出了语义化的标签，建议使用：section、aside、header、footer、article等HTML5布局标签。

2、自定义标签

标签元素名统一小写，不可大小写混合，有结尾标签的必须添加结尾标签相呼应。对于没有结尾标签的要在标签末尾加上“/”。

规范写法

<my-owner-components />
<my-owner-components></my-owner-components>

不友好写法

<myOwnerComponents />
<myOwnerComponents></myOwnerComponents>

3、多特性分行写

为提高可读性，组件应用时换行，按照ref、class、传入、传出顺序书写。
<scrollref="scrollWrap"class="home-scroll-warp":data="homeData":pullDownRefresh="true":pullUpLoad="true"@pullingDown="pullingDownGetNewData"@pullingUp="pullingUpGetMore">
</scroll>

4、使用表达式

在模版中使用表达式，复杂情况使用计算属性或函数

优雅写法

<template><div v-show="handleLimit(data)">测试数据</div>
</template>

export default {name: "Index",data() {return {};},methods: {/*** 显示判断* @param {Object} data 判断数据*/handleLimit(data) {return data.type !== "dir";},},
};

别扭写法

<div v-show="data.type !== 'dir' && dzqz && hasBtn && attrs.mode !== 'ended'">测试数据</div>

5、避免重复

避免过多重复代码，如果超过三行类似的代码，配置数据再循环遍历。

6、代码嵌套

根据元素嵌套规范，每个块状元素独立一行，内联元素可选。

规范写法

<div><h1></h1><p></p>
</div><p><span></span><span></span></p>

颠倒写法

<div><h1></h1><p></p>
</div><p><span></span><span></span>
</p>

推荐写法

<div><h1></h1><p></p>
</div><p><span></span><span></span>
</p>

7、活用v-show和v-if

v-show不会改变dom树，也就是说不会导致重排。
v-if会改变dom树，会导致重排。

注释规范

规范注释

<div><!-- test注释 --><div class="test">测试数据</div><!-- 组件注释 --><gd-custom-table ref="refTest"></gd-custom-table><!-- 其他注释 --><div>其他注释</div>
</div>

不友好注释

<div><div>测试数据</div><!-- 注释 -->
</div>

CSS规范

css部分，因为样式有原生写法和预处理写法scss/sass/less/stylus。所以情况比较多，也比较复杂，本文档统一使用scss。类名定义有多个单词时使用下划线区分，禁止使用横线连接，横线在Visual Studio Code编辑器中双击无法选中。

用法规范

1、避免

●避免使用标签选择器。因为在vue.js中，特别是在局部组件，使用标签选择器效率特别低，损耗性能，建议直接定义class；
●非特殊情况下，禁止使用id选择器定义样式。有JavaScript逻辑的情况除外；
●避免使用important选择器；
●避免大量的嵌套规则，控制在3级之内，对于超过4级的嵌套，考虑重写或新建子项；
●避免使用id选择器及全局标签选择器，防止污染全局样式。

2、推荐使用
●提取公用样式进assets文件的styles里，按模块/功能区分

|assets
|-- styles
|   |-- common          放置公用样式，如重置，混合，复写element样式等
|   |-- modules         放置模块样式

●推荐使用直接子选择器

/* 推荐 */
.jdc {
}.jdc li {
}.jdc li p {
}/* 不推荐 */
* {
}#jdc {
}.jdc div {
}

●使用scoped关键字，约束样式生效的范围

<style lang="scss" scoped>
.app_wrapper {
}
</style>

●使用变量

可复用属性尽量抽离为页面变量，易于统一维护。

<style lang="scss" scoped>
// CSS
.class_name {color: red;border-color: red;
}// SCSS
$color: red;
.class_name {color: $color;border-color: $color;
}
</style>

●使用混合(mixin)

根据功能定义模块，然后在需要使用的地方通过@include调用，避免编码时重复输入代码段。

<style lang="scss" scoped>
// CSS
.jdc_1 {-webkit-border-radius: 5px;border-radius: 5px;
}
.jdc_2 {-webkit-border-radius: 10px;border-radius: 10px;
}// SCSS
@mixin radius($radius: 5px) {// 当前代码可写入公用样式库mixin文件中-webkit-border-radius: $radius;border-radius: $radius;
}
.jdc_1 {// 参数使用默认值@include radius;
}
.jdc_2 {@include radius(10px);
}
</style>

●样式原子化(强烈推荐使用，也是本文档使用的方式)

需要在assets文件夹的styles里新建文件：display.css、width.css、height.css、margin.css、padding.css、color.css、background.css、font.css、public.css等，如有其它需要可继续创建文件，比如border.css。public.css文件用来引入其它子文件，最终把public.css文件引入到项目全局即可，并且public.css文件中可以写一些公共的样式，例如text-align: center;等。

<style lang="scss" scoped>
// margin
.mlr_a {margin-left: auto;margin-right: auto;
}.m_6 {margin: 6px;
}.ml_6 {margin-left: 6px;
}.mr_6 {margin-right: 6px;
}.mt_6 {margin-top: 6px;
}.mb_6 {margin-bottom: 6px;
}// padding
// padding与margin类似
// ...// display
.d_f {display: flex;
}.d_g {display: grid;
}.fd_c {flex-direction: column;
}.jc_s {justify-content: start;
}.jc_e {justify-content: end;
}.jc_sa {justify-content: space-around;
}.jc_c {justify-content: center;
}.ai_c {align-items: center;
}// width
.w_100 {width: 100px;
}.w_100vh {width: 100vh;
}.w_100_ {width: 100%;
}// height
// height与width类似// font
.fs_18 {font-size: 18px;
}.fw_600 {font-weight: 600;
}.fw_700 {// 700等与boldfont-weight: 700;
}.fw_bold {font-weight: bold;
}// color
.color_af {color: #afafaf;
}.color_333 {color: #333333;
}.color_362589 {color: #362589;
}.color_rgb_255 {color: rgb(255, 255, 255);
}.color_rgb_12_33_76 {color: rgb(12, 33, 76);
}.color_rgba_12_33_76_5 {// rgba中的a为1时改为rgb或者不标注1// 标注1表示的是0.1color: rgb(12, 33, 76, 0.5);
}// background
// background与color类似
.b_333 {background: #333333;
}.bc_333 {background-color: #333333;
}
</style>

书写顺序

css属性书写顺序，先决定定位宽高显示大小，再做局部细节修饰。
推荐顺序，定位属性(或显示属性，display)=>宽高属性=>边距属性(margin，padding)=>字体，背景，颜色等，修饰属性的定义，这样定义为了更好的可读性，让别人只要看一眼就能在脑海中浮现最终显示的效果。
●布局定位属性：display/position/float/clear/visibility/overflow
●自身属性：width/height/margin/padding/border/background
●文本属性：color/font/text-decoration/text-align/vertical-align/white- space/break-word
●其他属性(css3)：content/cursor/border-radius/box-shadow/text-shadow/background: linear-gradient
.class_name {position: fixed;top: 100px;left: 0;right: 0;bottom: 0;display: block;width: 100%;height: 100%;margin: 10px;padding: 10px;font-size: 14px;color: #000;background-color: red;border-radius: 2px;line-height: 1.42;
}

样式覆盖

组件内部需要覆盖UI框架样式，必须在最外层组件加类名。

<template><div class="input_area_container"><el-input class="name_input"></el-input></div>
</template><style lang="scss" scoped>
.input_area_container {.name_input {.el-input__inner {font-size: 16px;}}
}
</style>

注释规范

单行使用“// ”，双斜杠后面要加一个空格
多行使用 “/* 注释内容 */”，前后要有空格。
// 注释内容
.pha-element {width: 20px;// 这里需要换行.pha-element-l {/* 这里是多行注释这elementUi原样式类*/color: blue;}
}

JavaScript规范

用法规范

●在vue-cli脚手架使用框架自带的指向src开发目录的“@”符号引入文件资源；
●使用计算属性规避v-if和v-for用在一起；
●统一使用单引号；
●坚持单一原则，函数内仅做该函数应该做的，尽量避免通过传入标记控制不同行为；
●优先考虑三目运算符，但谨记不要写超过3层的三目运算符；
●对于无用代码必须及时删除，例如：一些调试的console语句、无用的弃用功能代码，如在开发分支可提交打印代码，但要注意打印格式；
●条件语句避免负面条件，特指调用某一函数；
// 推荐
function isUserNotBlocked(user) {}// 不推荐
if (!isUserNotBlocked(user)) {
}
●请求数据的方法，使用try…catch错误捕捉，注意执行回调。
●请求数据尽量使用async/await进行数据结构在使用，尽量少用then。
/**
* 接口请求
* @param req 接口api
* @param params 参数
*/
async handleList() {try {this.loading = true;let { result, total } = await getList(this.paramsQuery);this.list = result;this.total = total;} catch (error) {throw new Error(erroe);} finally {this.loading = false;}
}

组件选项

根据官方的推荐按照以下定义顺序使用。

export default {// 这个名字推荐：大写字母开头驼峰法命名name: "ExampleName",// Props定义props: {},// 组件定义components: {},// 指令定义directives: {},// 混入Mixin定义mixins: [],data() {// Data定义return {// Data属性的每一个变量都需要在后面写注释说明用途，就像这样dataProps: "",};},// 计算属性定义computed: {},// 属性变化监听器watch: {},// 生命钩子函数，按照他们调用的顺序created() {},// 挂载到元素mounted() {},// 使用keep-alive包裹的组件激活触发的钩子函数activated() {},// 使用keep-alive包裹的组件离开时触发的钩子函数deactivated() {},// 组件方法定义methods: {// 公共方法的定义，可以提供外面使用handleFn() {},// 私有方法，下划线定义，仅供组件内使用。多单词，注意与系统名字冲突_handleFn() {},},
};

注释规范

函数/方法注释必须包含说明，有参数和返回值时必须使用注释标识，它的作者、依赖关系和兼容性等信息。

1、单行注释，双斜线后应跟一个空格，且缩进与上下文的代码保持一致；禁止在行位注释，除非迫不得已，尽量在上一行添加注释

// 这是一个判断
if (condition) {
}

2、多行注释，一般用于注释难以理解的、可能存在错误的、逻辑强的代码，且缩进一致

/*** 数组求和* @param {Array} list 源数组* @returns 返回求和后的值*/
handleSum(list) {let sum = 0;sum = list;return sum;
}

3、函数注释，写明传入参数名称，类型，推荐完整注释以下格式

/**
* @Description 根据字典编码获取选项名称
* @Author lint
* @Date 2020-09-08
* @param {String} key 编码
* @param {String} val 值
* @returns {String} 字典名称
*/
handleDictText(key, val) {/*** @Description 加入购物车* @Author lint* @Date 2020-09-08* @param {Number} goodId 商品id* @param {Array<Number>} specs sku规格* @param {Number} amount 数量* @param {String} remarks 备注* @returns <Promise> 购物车信息*/apiProductAddCard = (goodId, specs, amount, remarks) => {return axios.post("***", { goodId, specs, amount, remarks });};const item = this.dictData[key].find((k) => k.dictKey === val);return item ? item.dictValue : "";
}

4、文件注释

/*** @Description: 文件名称* @Author: lint* @Date: 2020-09-08*/

5、命名要求

●变量的定义尽量使用let或cons，推荐使用let；
●基本类型的变量名尽量在名称后添加Val或Value，例如：let nameVal;
●引用数据类型尽量在变量名称后添加Obj或Arr或List，例如：let optionArr;
●函数或方法应该在名称前添加handle前缀，例如：handleList() {}；
●接口请求API的命名在前面添加请求类型，例如：getList、postAdd、putUpdate、deleteItem等。请求类型要全部大写，例如：GET、POST、PUT、DELETE等。

命名规范

目录命名

按照小驼峰命名，首字母小写。
项目文件夹：projectName
样式文件夹：styles/test.css或style/demo.scss
脚本文件夹：js/test.js或demo.ts

图片命名

图片使用img，图标使用icon。
●img_功能/类型_编号
●icon_功能/类型_编号

文件命名

1、按照小驼峰命令，英文单词过长或超出2个以上，可缩略至前四位

// 业务统计
approvalStatistical// 缩略
approvalStat

2、有复数含义，采用复数命名

pages
componets
filters
mixins
images

3、存放images、styles、icons等静态资源，静态资源命名格式为小驼峰或下划线，文件名为小驼峰，图片、图标或svg可以使用下划线

4、组件进行目录划分，目录命名为小驼峰，公用组件加上gd前缀

|components
|-- gdCustomCheck
|   |-- index.vue
|-- gdCustomTable
|   |-- index.vue

方法命名

method方法命名不同于文件命名，尽量完整英文命名，语义表达需完整清楚。

1、按照小驼峰命名法，可使用常见动词约定

●can判断是否可执行某个动作，函数返回一个布尔值。true(可执行)；false(不可执行)
●has判断是否含有某个值，函数返回一个布尔值。true(含有此值)；false(不含有此值)
●is判断是否为某个值，函数返回一个布尔值。true(为某个值)；false(不为某个值)
●get获取某个值，函数返回一个非布尔值
●set设置某个值，无返回值、返回是否设置成功或者返回链式对象load加载某些数据，无返回值或者返回是否加载完成的结果

2、语义化英文命名，仅组件内部使用方法前加上_(下划线)区分

export default {methods: {// 组件方法定义// 公共方法的定义，可以提供外面使用publicbFunction() {},// 私有方法，下划线定义，仅供组件内使用。多单词，注意与系统名字冲突_privateFunction() {},},
};

3、引入组件，首字母大写的驼峰法命名。推荐使用ES6的方式引入

import Article from "xxx";
import ArticleDetail from "xxx";

4、变量，使用驼峰式命名，优先使用let、const、避免使用var

let userName = "luffy";
const userInfo = {name: "luffy",
};

5、常量，字母全部大写，以下横线_划分

const Api = {// 获取事项分类ITEMS_OFONE_TYPE: "***",// 获取事项列表SOLUTION_LIST: "***",
};

样式命名

class命名以小写字母开头，小写字母、下划线(横线在Visual Studio Code编辑器中双击无法选中)和数字组成。不建议使用驼峰法命名class名称。
包裹层：.xx_wrap
列表：.xx_list
列表项：.xx_list_item
左边内容：.xx_left
中间内容：.xx_middle
右边内容：.xx_right
某个页面：.xx_page
某个盒子：.xx_box

常用词

1、常用动词

简写	说明
Get/set	取值/给值
Add/remove	增加/移除
Show/hide	显示/隐藏
view	查看
browse	浏览
edit	修改
save	保存
delete	删除
find	查询
undo	撤销
redo	重做
clean	清除
index	索引
observe	观察
Send/receive	发送/接收
Refresh/synchronize	刷新/同步

2、常用缩写

数据类型/标签	简写后缀
object	obj
array	arr
json	json
function	fn
message	msg
button	btn

工程结构

目录构建

|-- api                              所有api接口
|   |-- https                        封装的公用请求方法，除非必要不可修改，影响全局
|-- assets                           静态资源，images, icons, styles等
|   |-- images                       全局公用图片
|   |-- icons                        全局公用icons
|   |-- styles                       全局公用样式
|-- components                       公用组件
|   |-- base                         基础组件，导航，按钮，标签等组件
|   |-- business                     业务组件，封装可复用的页面或功能组件
|-- constants                        常量管理
|-- plugins                          插件管理
|-- router                           路由，统一管理
|-- store                            vuex, 统一管理
|-- utils                            工具管理
|   |-- utlis                        公共 JS 工具函数
|   |-- array                        数组类工具函数
|   |-- store                        存储类工具函数
|   |-- filters                      过滤器工具函数
|   |-- ...                              
|-- views                            视图目录（所有业务逻辑的页面）

文件说明

1、views里每个模块文件夹，都建一个文件说明，说明该视图模块；
2、api文件内采用ts写法，其中加入类型推断model，写清接口参数及参数类型；
3、提交代码时候要把断点，打印等去除；
4、文件、变量命名要尽量与后端保持一致；
5、无特殊情况统一用以下插件/工具/库，如需引用其他库，统一放置plugins文件内，注意按需引入。
●elementUI框架
●sass/css预处理器

代码风格

Eslint是识别和报告模式匹配的工具，它的目标是保证代码的一致性和避免错误，说白了就是用来检测代码风格的。在中大型项目中对维护项目的规范性、健壮性、可读性尤其有用。Vue CLI 3已经整合ESLint与著名的Airbnb JavaScript Style Guide，只要跟着Vue CLI 3的Wizard，我们也能轻易地将ESLint与Airbnb整合进Vue方案中。
1、依据以下三条原则，可以依据ESLint所有的配置项，定制出ESLint配置，原则上是对开发有益的都要开启
●能够帮助发现代码错误的规则，全部开启
●配置不应该依赖于某个具体项目，而应尽可能的合理
●帮助保持团队的代码风格统一，而不是限制开发体验
2、接入项目的方法
●在Visual Studio Code中安装Eslint和Prettier两个插件
●执行npm install husky lint-staged eslint eslint-plugin-vue