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

MENU

• 前言
• • 目的
• 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、传入、传出顺序书写。

<scroll
     ref="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等与bold
  font-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.1
  color: 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、常用动词

2、常用缩写

工程结构

目录构建

|-- 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

Git规范

目前按照我们正常开发的项目，master分支作为主干分支，及生产环境，多人协同开发时一定要按照分支规范去建立和提交分支。

分支说明

●master分支：主干分支，与线上正式版本保持一致
●dev分支：开发分支，始终与master分支保持一致
●feature分支：版本开发分支(多个)
●test分支：版本测试分支(多个，对应feature)
●release分支：预发布分支
●bug分支：用来修改bug的分支

使用说明

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

相关连接

1、CSDN-前端开发规范详解
2、稀士掘金-前端代码规范 –代码规范篇
3、稀士掘金-前端开发规范V2022.3