前端代码规范

关于注释问题

注释规遵循jsDoc

类注释（多行注释）

/**
 * 工具类
 * @author 丁少华
 * @date 2020-01-01 08:00:00
 */

方法注释（多行注释）

/**
  * 用于xxx
  * @param {string} uid - 用户id
  * @return {User} 一个用户
  */

属性注释（单行注释）

// 用户的id
let uid = '12345';

html注释

<!--region 选择框-->
<el-table-column  type="selection"/>
<!--endregion-->

快捷键配置

如果嫌注释麻烦，网上有很多编辑器设置注释模板的配置

关于编码规范

行数

单个文件总行数不得超过600行
vue的template不得超过300行
单个vue组件内，若样式超出100行，样式需独立出来

命名规范

代码中，除了js部分可以用驼峰命名外，其他均用中划线方式
代码中，js部分命名遵循常规命名规范，并命名要有意义，禁止用拼音和单字符做key
代码中，代码整齐，不要有多余的空格和行数，书写代码的时候就要注意
文件中，文件夹，文件（vue、js、less）均使用中划线命名方式

关于缩进

缩进均用两个space代替，禁止使用tab

关于ts

详细文档参考官方文档
属性，方法形参和返回值都必须要有类型
在任何时候都不要有限考虑用any作为类型

vue和element ui

使用路由时，用路由名称（定义的枚举）来访问，方便以后维护
使用饿了么ui的表单，label可以添加label-suffix为label添加冒号

优秀的习惯

书写代码要思考

书写代码一定要想好，规划好再编写，切勿无脑从上到下机械的写下去。
如果工作内容成了一个体力活，那就要认真反思了

模块化

以下情况下，要考虑抽离组件或提取代码，切分模块

组件代码较长，且部分代码逻辑较为独立
有多个地方用到

其他

ajax我会封装一个类，不能在组件内直接用aixos发请求，并须有层封装
团队步调要一致，如果有更好的方案，可以讨论决定，不得擅自改变规则

-------以下为公司原始文档------------

---分割线---

目前前端技术栈以Vue2.0为主，小程序开发主要以WePY为开发框架；所以规范主要以Vue为基础，主要包括JS、Css、文件命名、项目结构、注释

1技术栈
2项目结构
- 2.1整体结构
- 2.2views层结构规范
3文件命名
- 3.1文件夹命名、文件命名、组件命名
- 3.2函数、变量、常量、css类名、标签命名
  - 3.2.1函数、变量
  - 3.2.2常量
  - 3.2.3css类名
  - 3.2.4标签
- 3.3注释
  - 3.3.1单行注释
  - 3.3.2多行注释
  - 3.3.3函数注释
  - 3.3.4html块级注释
  - 3.3.5文件自动生成注释头信息
4其它
- 4.1尽量使用缩写属性
- 4.2尽量使用缩写属性对于代码效率和可读性是很有用的
- 4.3零后面不带单位
- 4.4组件的 data 必须是一个函数
- 4.5Prop
- 4.6为 v-for 设置键值
- 4.7避免 v-if 和 v-for 用在一起
- 4.8为组件样式设置作用域
- 4.9使用 TODO 标注问题的解决方式
- 4.10vue文件中的指令缩写
- 4.11跨域
- 4.12状态管理
- 4.13调试
- 4.14浏览器适配

技术栈

vue全家桶、相关生态、ts/ES6、tslint/eslint、less、组件库：PC：element-ui，移动端：vant，
开发相关：WebStorm/VS code、git、pxcook(账号使用中文名)、Chrome/firefox

项目结构

这只是项目模板中的基础结构，具体需要结合项目需求进行定制化修改；以下项目结构基本上可以满足项目开发。

整体结构

api：接口请求Api层
assets：静态资源文件
base：BLL业务逻辑层基类（构造函数）
components：公共组件
utils：工具箱帮助
plugins：插件
types：类型定义文件
directives：自定义指令
router：路由文件
styles：公用样式
views：组件
store：vuex持久化

views层结构规范

views层是表现层，为了避免单个文件代码量过大的隐患，Vue组件采用 template、styles、js 分离的形式，外层采用业务文件夹命名的方式。结构清晰、单个文件的代码量较少、后期易于维护、特殊组件/文件置于业务文件夹。
分离规则：js>200行与 css>100行将js & css 单独抽出

-views
  -home-page
    index.vue
    index.js
    index.less

文件命名

文件夹命名、文件命名、组件命名

命名规则：kebab-case命名规范（短横线命名）
不能含有特殊字符、空格
文件名应该更倾向于完整单词而不是缩写
vue文件命名：统一使用小写字母开头的(kebab-case)命名规范；非vue文件（ts、js、css、less……）
组件必须包含 name 属性
全局通用的组件放在/src/components下
应该以一个特性的前缀开头，比如 v
组件名称 name: 使用大写字母开头的 PascalBase 风格

-src
  -components
    -v-table
      index.vue
    -v-svg-icon
      index.vue

其它业务页面中的组件，放在个子页面下的 ./components文件夹下

-home-page
  -components
    pan-item.vue
index.vue
  index.js
  index.less

函数、变量、常量、css类名、标签命名

命名使用英文，不允许出现拼音、拼音首字母等命名，要求通俗易懂

函数、变量

命名规则：小驼峰
且变量定义方式必须使用 let，不允许使用 var

let tempName =function initData() {}

常量

命名规则：全部大写：使用大写字母和下划线组合命名，下划线用于分隔单词
此规则适用于位于文件顶部常量、独立的常量文件中的命名，如果是方法体内部的常量，应当使用小驼峰的命名规则

const CASE_ID = 'XXX'

css类名

命名规则：class为完整小写单词并以 - 连接

.form-input {font-size:14px;color:#333333;}

尽量不要使用内嵌式style
注：ID的权重高，一般情况下，不应用于样式；如果需要使用 ID 解决样式的优先级，ID的命名规则为：帕斯卡命名法

标签

非 Html 标签，比如：组件名（参照文件命名：kebab-case命名规范），则在template中，组件引用使用小写单词且用 - 连接

<template>
  <i-table></i-table>
</template>
<script>
import iTable from '@/components/iTable/index.vue'
 
export default {
  components: { ITable },
  ...
}
</script>

注释

项目中使用到的注释一般为：文件头注释、html块级注释、多行注释、单行注释、函数注释；且完整项目中的代码注释量不能少于代码总量的30%。

单行注释

单独一行：// （双斜杠）与注释内容之间保留一个空格
在代码后添加注释：// （双斜杠）与代码之间保留一个空格，同时与注释内容之间保留一个空格

let userName = '哈哈'; // 登录名

多行注释

以 /* 开头，以 */ 结尾，且与注释内容之间保留一个空格

/*  this.tableCurrentPagination = {            
    pageIndex: 1,            
    pageSize: size   
 }  */

函数注释

函数注释也是多行注释的一种

/**
   * 取消收藏
   */

html块级注释：

可以将 html dom 按照功能块级折叠，方便阅读和维护

<!--region 选择框-->
<el-table-column v-if="options.mutiSelect" type="selection" style="width: 55px;">
</el-table-column>
<!--endregion-->

注：webstorm已经配置了注释模板，输入 re 点击 Tab即可

文件自动生成注释头信息

Js文件

/**
 * @Author : ChangJun
 * @Date : 2018/10/27
 * @Version : 1.0
 * @Content : 接口层
 */

Vue文件

<!--
* @Author : ChangJun
* @Date :  2018/12/13
* @Version : 1.0
* @Content :
-->

Css文件

/**
 * @Author : ChangJun
 * @Date : 2018/12/13
 * @Version : 1.0
 * @Content :
 */

注：webstorm设置中，添加自动生成注释头信息

其它

尽量使用缩写属性

尽量使用缩写属性对于代码效率和可读性是很有用的

正例：

border-top: 0;
padding: 0 1em 2em;

反例：

padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;

0 后面不带单位

正例：

padding-bottom: 0;
margin: 0;

反例：

padding-bottom: 0px;
margin: 0em;

组件的 data 必须是一个函数

当在组件中使用 data 属性的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。

data () {
    return {
      pageIndex: 1,
      tableCurrentPagination: {},
      multipleSelection: [] // 多行选中
    }
  }

Prop

Prop定义应该尽量详细，必须指定其类型

props: {
  total: {
    type: Number,
    default: 0
  }, // 总数
  pagination: {
    type: Object,
    default: null // 分页参数 === pageSize:每页展示的条数，pageIndex:当前页，pageArray: 每页展示条数的控制集合，默认 _page_array
  }
}

为 v-for 设置键值

在组件上总是必须用 key 配合 v-for，以便维护内部组件及其子树的状态

<ul>
  <li v-for="todo in todos" :key="todo.id">
     {{ todo.text }}
  </li>
</ul>

避免 v-if 和 v-for 用在一起

永远不要把 v-if 和 v-for 同时用在同一个元素上

<ul v-if="shouldShowUsers">
  <li v-for="user in users" :key="user.id">
    {{ user.name }}
  </li>
</ul>

为组件样式设置作用域

对于用于来说，顶级App组件和布局组件的样式可以是全局的，但是其它所有组件都应该是有作用域的。这条规则只和单文件组件有关。你不一定要使用 scoped 特性。

<template>
  <button class="button button-close">X</button>
</template>
<!-- 使用 `scoped` 特性 -->
<style scoped>
.button {
  border: none;
  border-radius: 2px;
}
.button-close {
  background-color: red;
}
</style>

使用 TODO 标注问题的解决方式

vue文件中的模块顺序

<template></template>
<script></script>
<style></style>

vue文件中的指令缩写

指令缩写 (用 : 表示 v-bind:和用 @表示 v-on:)

跨域

跨域线下通过
proxytable解决，线上通过运维配置Nginx代理

状态管理

如果需要缓存，使用vuex-persistedstate

调试

避免线上环境出现控制台输出、警告、报错等信息
推荐使用console.debug

浏览器适配

IE 8及以下不做考虑，使用polyfill
typescript
装饰器
参数要声明类型，尽量不要使用any
单组件类名与文件名保持一致

posted @ 2023-01-12 10:43 丁少华阅读(114) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部