目的及文档说明

规范的目的是为了统一编码风格规范，提高代码质量和可读性，增强团队协作开发效率（参考腾讯、百度、字节跳动，同时参考前端代码规范 --代码规范篇 - 掘金 (juejin.cn)^[1]等前端规范）

HTML 规范

2.1.语义化标签

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

2.2.自定义标签

使用自闭标签的写法，如下

<my-owner-components />

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">
  <!-- 组件注释 -->
  <gdCustomTable ref="gdCustomTable" />
  <!-- 其他注释 -->
  <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)
    returnPromise.resolve(res)
  } catch (e) {
    returnPromise.reject(e)
  } finally {
    loading.value = false
  }
}

4.9.注释规范

1. 单行注释：双斜线后应跟空格，且缩进与上下文的代码保持一致；或在行尾注释，在行尾依然需要左右空格；

// 一些说明...
const userID = 24;
const userID = 12; // 一些说明

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

/*
* 针对下方代码的说明
* 第一行太长写第二行
*/
const a = 1；

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

/**
* @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）
• 组件目录命名 目录命名为小驼峰，公用组件加上 gd 前缀，如：

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

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 加载某些数据,无返回值或者返回是否加载完成的结果

2. 语义化英文命名，仅组件内部使用方法前加上_（下划线）区分，如下

// 公共方法的定义，可以提供外面使用
publicbFunction () {}

// 私有方法，下划线定义，仅供组件内使用。多单词，注意与系统名字冲突！
_privateFunction () {}

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

import Article from'xxx'
import ArticleDetail from'xxx'

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

let userName = ref('luffy')

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

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

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

5.5.常用词

1. 常用动词

2. 常用缩写

5.6.样式命名

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

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

Git 规范

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

• master 分支：主干分支，与线上正式版本保持一致
• dev 分支：开发分支，始终与 master 分支保持一致
• feature 分支：版本开发分支（多个）
• test 分支：版本测试分支（多个，对应 feature）
• release 分支：预发布分支
• bug 分支

6.1.分支关系

6.2.使用说明

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