前端代码规范

糖baobao
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. 变量：使用驼峰式命名，优先使用let、const、避免使用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分支可提交打印说明，注意打印说明格式，其他分支不可提交；
  • 提交时尽量书写提交代码修改的地方或功能，不要提交无用信息；
avatar
文章
阅读
粉丝