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

本文介绍: web前端开发规范、HTML规范、JavaScript规范、style规范

前言

目的

规范的目的是为了编写高质量的代码，提高代码质量和可读性，增强团队协作开发效率，统一编码风格。
文档说明
本文旨在统一团队前端代码规范，参考腾讯、百度、字节跳动等前端规范，结合团队日常业务需求以及团队日常开发过程中的总结而制定，如果发现错误敬请指正

HTML规范

用法规范

1、语义化标签

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

2、自定义标签

标签元素名统一小写，不可大小写混合，有结尾标签的必须添加结尾标签相呼应。对于没有结尾标签的要在标签末尾加上“/”。

规范写法

<my-owner-components /&gt;
<my-owner-components&gt;</my-owner-components&gt;

不友好写法

<myOwnerComponents /&gt;
<myOwnerComponents&gt;</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、常用动词

简写	说明
Get/set	取值/给值
Add/remove	增加/移除
Show/hide	显示/隐藏
view	查看
browse	浏览
edit	修改
save	保存
delete	删除
find	查询
undo	撤销
redo	重做
clean	清除
index	索引
observe	观察
Send/receive	发送/接收
Refresh/synchronize	刷新/同步

2、常用缩写

数据类型/标签	简写后缀
object	obj
array	arr
json	json
function	fn
message	msg
button	btn

工程结构

目录构建

|-- 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分支可提交打印说明，注意打印说明格式，其他分支不可提交；
●提交时尽量书写提交代码修改的地方或功能，不要提交无用信息。

MENU

前言

目的

HTML规范

用法规范

注释规范

CSS规范

用法规范

书写顺序

样式覆盖

注释规范

JavaScript规范

用法规范

组件选项

注释规范

命名规范

目录 命名

图片命名

文件命名

方法命名

样式命名

常用词

工程结构

目录构建

代码风格

Git规范

分支说明

使用说明

相关连接

发表回复取消回复

MENU

前言

目的

HTML规范

用法规范

注释规范

CSS规范

用法规范

书写顺序

样式覆盖

注释规范

JavaScript规范

用法规范

组件选项

注释规范

命名规范

图片命名

文件命名

方法命名

样式命名

常用词

工程结构

目录构建

代码风格

Git规范

分支说明

使用说明

相关连接

相关文章

发表回复 取消回复

发表回复取消回复