前端代码规范

大王棒棒的
192 阅读8分钟

引言

1.1 目的

规范的目的是为了编写高质量的代码，提高代码质量和可读性，增强团队协作开发效率，统一编码风格规范

1.2 文档说明

本文旨在统一团队前端代码规范，参考腾讯、百度、字节跳动等前端规范，结合团队日常业务需求以及团队日常开发过程中的总结而制定，如果发现错误敬请指正~

HTML规范

2.1 用法规范

  1. 语义化标签

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

  1. 自定义标签

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

 <MyComponents />
  1. 多特性分行写

为提高可读性，组件应用时换行，按照ref、class、传入、传出顺序书写，如下：

<template>
  <scroll
    ref="scrollWrap"
    class="home-scroll-warp"
    :data="homeData"
    :pullDownRefresh="true"
    :pullUpLoad="true"
    @pullingDown="pullingDownGetNewData"
    @pullingUp="pullingUpGetMore"
  />
</template>
  1. 使用表达式

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

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

// 反例 
<template> 
    <div v-show="data.type !== 'dir' && dzqz && hasBtn && attrs.mode !== 'ended'"> ... </div>  
</template>
  1. 避免重复

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

  1. 代码嵌套

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

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

// 第二种 
<div> 
    <h1></h1>
    <p></p> 
</div> 
<p> 
    <span></span> 
    <span></span> 
</p>
  1. 活用v-show，v-if(不要同时出现在一个标签上）
  • v-show不会改变dom树，也就是说不会导致重排。
  • v-if会改变dom树，会导致重排。

2.2 注释规范

<!-- test注释 -->
<div class="test">
  <!-- 组件注释 -->
  <gdCustomTable ref="gdCustomTable"  />
  <!-- 其他注释 -->
  <div>...</div>
</div>

CSS规范

css部分，因为样式有原生的 CSS 写法，也有使用预处理语言：Sass, Less，Stylus。所以情况比较多，也比较复杂。我们统一使用 Sass

3.1 用法规范

  1. 避免：
  • 避免使用标签选择器以及ID 选择器。因为在 Vue 中，特别是在局部组件，使用标签选择器效率特别低，损耗性能，建议需要的情况，直接定义 class；
  • 避免使用important选择器；
  • 避免大量的嵌套规则，控制在3级之内，对于超过4级的嵌套，考虑重写或新建子项；
  • 避免使用全局标签选择器防止污染全局样式；
  1. 推荐使用
  • 提取公用样式进assets文件styles里，按模块/功能区分；
|assets
|-- styles
|   |-- common          放置公用样式，如重置，混合等
    |-- element         复写element样式
|   |-- modules         放置模块样式
  • 推荐使用直接子选择器；
/* 推荐 */
.jdc {}

/* 不推荐 */
*{}
#jdc {}
  • 使用 scoped 关键字，约束样式生效的范围
<style lang="scss" scoped>
.app-wrapper {
  ...
}
</style>
  • 使用变量

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

:root {
  --theme-background: 247, 250, 252;
  --scrollbar: #e5e5e5;
  --module-bg: rgb(4 32 103 / 50%);
}
:root[theme='dark'] {
  --theme-background: 18, 18, 18;
  --scrollbar: #515151;
}

html {
  &::-webkit-scrollbar {
    // 定义了滚动条整体的样式；
    width: 6px;
    height: 6px;
    background-color: var(--scrollbar);
  }
  &::-webkit-scrollbar-thumb {
    width: 5px;
    height: 5px;
    border-radius: 8px;
    background-color: var(--scrollbar);
  }
  &::-webkit-scrollbar-track {
    border-radius: 10px; // 轨道圆角
    background-color: rgb(var(--theme-background)) !important; // 轨道颜色
  }
}
  • 使用混合（mixin）

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

// 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);
}

3.2 书写顺序

CSS 属性书写顺序：先决定定位宽高显示大小，再做局部细节修饰，推荐顺序：

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

  1. 布局定位属性：position / display / float / clear / visibility / overflow
  2. 自身属性：width / height / margin / padding / background / border / border-radius
  3. 文本属性：font / color / text-decoration / text-align / vertical-align / white-space / break-word
  4. 其他属性（CSS3）：content / cursor / box-shadow / text-shadow…

以下给出常用的定义示例：

.class-name {
  position: fixed;
  top: 100px;
  left: 0;
  right: 0;
  bottom: 0;
  display: block;
  width: 100%;
  height: 100%;
  margin: 10px;
  padding: 10px;
  background-color: red;
  border-radius: 2px;
  font-size: 14px;
  color: #000;
  line-height: 1.42;
}

3.3 注释规范

以/ 注释内容 /格式注释，前后空格

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

JS规范

4.1 用法规范

  1. 使用'@' 符号引入文件资源；
  2. 规避 v-if 和 v-for 用在一起；
  3. 坚持单一原则，函数内仅做该函数应该做的，尽量避免通过传入标记控制不同行为；
  4. 优先考虑三目运算符，但谨记不要写超过3层的三目运算符；
  5. 对于无用代码必须及时删除，例如：一些调试的 console 语句、无用的弃用功能代码，如在开发分支可提交打印代码，但要注意打印格式，如下：
// 推荐
console.log('路由': 文件路由, '打印简述': 打印数据)

// 不推荐
console.log(打印数据, '1111')

4.2 注释规范

函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。

  1. 单行注释：双斜线后应跟空格，且缩进与上下文的代码保持一致；或在行尾注释，在行尾依然需要左右空格；
// 一些说明...
const userID = 24;
const userID = 12; // 一些说明
  1. 多行注释：一般用于注释难以理解的、可能存在错误的、逻辑强的代码，且缩进一致；
/*
 * 针对下方代码的说明
 * 第一行太长写第二行
 */
const a = 1；
  1. 函数注释：写明传入参数名称，类型，推荐完整注释以下格式；
/**
 * @Description 加入购物车
 * @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 })
}
  1. 文件注释；
/**
 * @Description: 文件名称
 * @Author:	lint
 * @Date: 2020-09-08
 */

命名规范

5.1 文件目录命名

按照小驼峰命名，首字母小写

  • 项目文件夹：projectName
  • 样式文件夹：css / scss
  • 脚本文件夹：js

5.2 图片命名

图片命名建议以以下顺序命名：

图片业务（可选） +（mod_）图片功能类别（必选）+ 图片模块名称（可选)

  • 图片业务：

    • dp_：大屏
    • ht_: 后台
    • …

  • 图片功能类别：

    • mod_：是否公共，可选
    • icon：模块类固化的图标
    • logo：LOGO类
    • spr：单页面各种元素合并集合
    • btn：按钮
    • bg：可平铺或者大背景
    • …

  • 图片模块名称：

    • header：头部
    • card：卡片区块
    • …
公共模块： 
dp_mod_btn_check.png 
dp_mod_btn_close.png 

非公共模块： 
ht_btn_ok.png 
btn_ok.png

5.3 公用组件命名

组件进行目录划分，目录命名为大驼峰，如

|components
    |-- WangDrawer
        |-- index.vue
    |-- WangEcharts
        |-- index.vue

通过unplugin-vue-components插件实现组件的自动按需导入

安装：

npm i unplugin-vue-components -D

配置：vite.config.js

import Components from 'unplugin-vue-components/vite'
// ui库解析器，也可以自定义，需要安装相关UI库，unplugin-vue-components/resolvers
// 提供了以下集中解析器，使用的时候，需要安装对应的UI库，这里以element为示例
import {
  ElementPlusResolver,
  // AntDesignVueResolver,
  // VantResolver,
  // HeadlessUiResolver,
  // ElementUiResolver
} from 'unplugin-vue-components/resolvers'

export default  ({ mode }) => defineConfig({
  plugins: [
    Components({
      dirs: ['src/components'], // 目标文件夹
      extensions: ['vue','jsx'], // 文件类型
      dts: 'src/components.d.ts', // 输出文件，里面都是一些import的组件键值对
      // ui库解析器，也可以自定义，需要安装相关UI库
      resolvers: [
        VantResolver(),
          ElementPlusResolver(),
        // AntDesignVueResolver(),
        // HeadlessUiResolver(),
        // ElementUiResolver()
      ],
    })
  ]
})

5.4 方法命名

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

  1. 按照小驼峰命名法，可使用常见动词约定；
  • can 判断是否可执行某个动作，函数返回一个布尔值。true：可执行；false：不可执行
  • has 判断是否含有某个值， 函数返回一个布尔值。- true：含有此值；false：不含有此值
  • is： 判断是否为某个值，函数返回一个布尔值。true：为某个值；false：不为某个值
  • get： 获取某个之，函数返回一个非布尔值
  • set： 设置某个值，无返回值、返回是否设置成功或者返回链式对象 load 加载某些数据,无返回值或者返回是否加载完成的结果
  1. 变量：使用驼峰式命名，优先使用let、const、避免使用var
let userName = 'luffy'
const userInfo = {
  name: 'luffy'
}
  1. 常量：字母全部大写，以下横线_划分
const Api = {
  ITEMS_OFONE_TYPE = '***', // 获取事项分类
  SOLUTION_LIST = '***',, // 获取事项列表
}

5.5 样式命名

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

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

5.6 常用词

  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

参考：
京东代码规范
我的前端工程化宝典，分享给你
前端代码规范 --代码规范篇

avatar
文章
阅读
粉丝