前端代码规范

6,883 阅读8分钟

目的及文档说明

规范的目的是为了统一编码风格规范,提高代码质量和可读性,增强团队协作开发效率(参考腾讯、百度、字节跳动等前端规范)

HTML规范

2.1.语义化标签

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

2.2.自定义标签

推荐使用自闭合标签的写法(自闭合标签不使用连线方式),如下

 <MyComponents />
2.3. 多特性分行写
<template> 
   <scroll 
      ref="scrollWrap" 
      class="home-scroll-warp" 
      :data="homeData" 
      :pullDownRefresh="true" 
      :pullUpLoad="true" 
      @pullingDown="pullingDownGetNewData" 
      @pullingUp="pullingUpGetMore" 
   />
</template>
2.4. 使用表达式

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

<template>
  <div v-show="getLimitData(data)"> 
   ... 
  </div>
</template>

// 反例
<template> 
  <div v-show="data.type !== 'dir' && dzqz && hasBtn && attrs.mode !== 'ended'"> 
   ... 
  </div> 
</template>
2.5.代码嵌套

根据元素嵌套规范,每个块状元素独立一行,内联元素可选,如下:

// 第一种
<div>
  <h1></h1>
  <p></p>
</div> 
<p><span></span><span></span></p>

// 第二种
<div>
  <h1></h1><p></p>
</div>
<p> 
  <span></span>
  <span></span>
</p>
2.6.避免重复

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

2.7.活用v-show, v-if (不要同时出现在一个标签上)
  • v-show不会改变dom树,也就是说不会导致重排。
  • v-if会改变dom树,会导致重排。
2.7注释规范
<!-- 单行注释 -->
<div class="test">
  <!-- 组件注释 -->
  <CustomTable ref="customTableRef" />
  <!-- 其他注释 -->
  <div>...</div>
</div>

<!-- 
  多行注释
  多行注释
-->
<div>内容</div>
  

CSS规范

推荐使用UnoCSS引擎进行原子化CSS开发 推荐使用scss预编译 由于样式的情况比较多也比较复杂 做出如下规范

3.1.避免
  • 避免使用标签选择器。因为在 Vue 中,特别是在局部组件,使用标签选择器效率特别低,损耗性能,建议需要的情况,直接定义 class;

  • 非特殊情况下,禁止使用 ID 选择器定义样式。有 JS 逻辑的情况除外;

  • 避免使用important选择器;

  • 避免大量的嵌套规则,控制在3级之内,对于超过4级的嵌套,考虑重写或新建子项;

  • 避免使用ID选择器及全局标签选择器防止污染全局样式;

3.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>
  • 使用变量 可复用属性尽量抽离为页面变量,易于统一维护
/* css */ 
.class-name { 
  color: red;
  border-color: red; 
} 

/* scss */  
$color: red; 
.class-name { 
  color: $color;
  border-color: $color; 
}
3.3.书写顺序

CSS 属性书写顺序:先决定定位宽高显示大小,再做局部细节修饰,推荐顺序(可以提升浏览器渲染 dom 的性能):

定位属性(或显示属性,display)->宽高属性->边距属性(margin, padding)->字体,背景,颜色等,修饰属性的定义,这样定义为了更好的可读性,让别人只要看一眼就能在脑海中浮现最终显示的效果。

  1. 布局定位属性:display / position / float / clear / visibility / overflow

  2. 自身属性:width / height / margin / padding / border / background

  3. 文本属性:color / font / text-decoration / text-align / vertical-align / white- space / break-word

  4. 其他属性(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; 
}
3.4.样式覆盖

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

3.5.注释规范

以/ 注释内容 /格式注释,前后空格,嵌套子类需要一个回车分割开

/* 注释内容 */
.pha-element {
  width: 20px;
  /* 这里需要换行 */ 
  .pha-element-l { 
    color: blue 
  } 
}

JS规范

4.1.在vue-cli 脚手架使用架自带的指向 src 开发目录的 '@' 符号引入文件资源;
4.2.使用计算属性规避 v-if 和 v-for 用在一起;
4.3.统一使用单引号;
4.4.坚持单一原则,函数内仅做该函数应该做的,尽量避免通过传入标记控制不同行为;
4.5.优先考虑三目运算符,但谨记不要写超过3层的三目运算符;
4.6.对于无用代码必须及时删除,例如:一些调试的 console 语句、无用的弃用功能代码,如在开发分支可提交打印代码,但要注意打印格式,如下:
// 推荐 
console.log('路由': 文件路由, '打印简述': 打印数据) 

// 不推荐 
console.log(打印数据, '1111')
4.7.条件语句避免负面条件,特指调用某一函数;
// 不推荐 
if (!isUserNotBlocked(user)) { 
  // ... 
}
4.8.请求数据的方法,推荐使用async await, 需注意错误捕捉
/** 
* 接口请求 
* @param req 接口api 
* @param params 参数 
*/ 
const loading = ref(false)
async httpInterface(req, params) { 
  try { 
    loading.value = true 
    const res = await req(params) 
    return Promise.resolve(res) 
  } catch (e) { 
    return Promise.reject(e)
  } finally { 
    loading.value = false 
  } 
}
 
4.9.注释规范
  1. 单行注释:双斜线后应跟空格,且缩进与上下文的代码保持一致;或在行尾注释,在行尾依然需要左右空格;
// 一些说明... 
const userID = 24; 
const userID = 12; // 一些说明
  1. 多行注释:一般用于注释难以理解的、可能存在错误的、逻辑强的代码,且缩进一致;
/* 
* 针对下方代码的说明 
* 第一行太长写第二行 
*/ 
const a = 1
  1. 函数注释:写明传入参数名称,类型,推荐完整注释以下格式;
/** 
* @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 }) 
}

命名规范

5.1.目录命名
  • 文件目录命名 按照小驼峰命名,首字母小写(如:projectName)
  • 组件目录命名 按照大驼峰命名,如下:
|-- components
| |-- ProjectName
| | | -- ProjectName.vue
| | | -- index.js
5.2.文件命名

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

// 业务统计 
approvalStatistical 

// 缩略 
approvalStat
5.3.图片命名

图片使用img,图标使用icon

  • img_功能/类型_编号
  • icon_功能/类型_编号
5.4.方法命名
  1. 按照小驼峰命名法,可使用常见动词约定;
  • can 判断是否可执行某个动作,函数返回一个布尔值。true:可执行;false:不可执行
  • has 判断是否含有某个值, 函数返回一个布尔值。- true:含有此值;false:不含有此值
  • is: 判断是否为某个值,函数返回一个布尔值。true:为某个值;false:不为某个值
  • get: 获取某个之,函数返回一个非布尔值
  • set: 设置某个值,无返回值、返回是否设置成功或者返回链式对象 load 加载某些数据,无返回值或者返回是否加载完成的结果
  1. 语义化英文命名,仅组件内部使用方法前加上_(下划线)区分,如下
// 公共方法的定义,可以提供外面使用
publicbFunction () {} 

// 私有方法,下划线定义,仅供组件内使用。多单词,注意与系统名字冲突!
_privateFunction () {} 
  1. 引入组件:首字母大写的驼峰法命名。推荐使用 ES6 的方式引入
import Article from 'xxx' 
import ArticleDetail from 'xxx'
  1. 变量:使用驼峰式命名,优先使用letconst、避免使用var
let userName = ref('luffy')

const userInfo = reactive({ 
  name: 'luffy'
})

  1. 常量:字母全部大写,以下横线_划分
const Api = { 
  ITEMS_OFONE_TYPE = '***', // 获取事项分类 
  SOLUTION_LIST = '***',, // 获取事项列表
}
5.5.常用词
  1. 常用动词
简写说明
get\set取值\给值
add\remove增加\移除
show\hide显示\隐藏
view查看
browse浏览
edit修改
save保存
delete删除
find查询
undo撤销
redo重做
clean清除
index索引
observe观察
send\receive发送\接收
refresh\synchronize刷新\同步
  1. 常用缩写
数据类型/标签简写后缀
objectobj
arrayarr
jsonjson
functionfn
messagemsg
buttonbtn
5.6.样式命名

class命名以小写字母开头,小写字母、中划线和数字组成。不建议使用驼峰法命名 class 的属性。以下是一些常用到的 class的名字:

  • 包裹层: .xx-wrap;
  • 列表: .xx-list;
  • 列表项: .xx-list-item; 
  • 左边内容: .xx-left; 
  • 中间内容: .xx-middle; 
  • 右边内容: .xx-right; 
  • 某个页面: .xx-page;

Git规范

master分支作为主干分支,及生产环境,多人协同开发时一定要按照分支规范去建立和提交分支,具体如下:

  • master分支:主干分支,与线上正式版本保持一致
  • dev分支:开发分支
  • feature分支:版本开发分支(多个)
  • test分支:版本测试分支(多个,对应feature)
  • release分支:预发布分支
  • bug分支
6.1.分支关系

image.png

6.2.使用说明
  • 多人在同一个分支上开发时,分支名称可按照版本号命名,注意记录版本号对应功能点;
  • dev分支可提交打印说明,注意打印说明格式,其他分支不可提交;
  • 提交时尽量书写提交代码修改的地方或功能,不要提交无用信息;