crm-project/STANDARD.md

HTML

缩进

• 使用一个制表符（两个空格）为一次缩进

单双引号

• 默认使用双引号

变量使用{{}}

• {{}}与变量之间空一格

{{ user.name }}

减少标签的使用和嵌套

• 尽可能避免无意义的标签嵌套，做到精简

静态样式与动态样式区分

• 动态样式可以写到style属性内
• 静态样式尽可能拆分写在wxss文件中

语义化

• 标签的选择做到语义化
• 标签的class命名做到语义化
• 避免简写命名
  • 例如：class="news-p"或者"p"这种

换行

• 标签内的属性很多的时候，建议换行（超过4个必须换行：4个及4个以上）

<view
  wx:if="{{ type === 'spinner' }}"
  wx:for="item in 12"
  wx:key="index"
  class="van-loading__dot"
/>

CSS样式规范

命名

class命名必须按照以下规范进行命名

• .block
  • 某个类
• .block__child
  • 某个类的子元素
• .block--modifier
  • 某个类的不同状态

<ul class="news">
    <li class="news__item"></li>
    <li class="news__item"></li>
    <li class="news__item--active"></li>
<ul>

模块区分

• wxss代码中对应wxml做好一定的代码区分

<div class="header">
    ...
</div>
<div class="content">
    ...
</div>
<div class="footer">
    ...
</div>

/*---------- header begin ----------*/
.header {
    ...
}

/*---------- content begin ----------*/
.content {
    ...
}
/*---------- footer begin ----------*/
.footer {
    ...
}

状态样式，非模块、元素样式，提到最上面

/**
 * action
 * 被选中的样式
 */
.action {
    ...
}
/*---------- header begin ----------*/
.header {
    ...
}

/*---------- content begin ----------*/
.content {
    ...
}
/*---------- footer begin ----------*/
.footer {
    ...
}

多个选择器指定样式时，每个选择器单独占用一行

/* 不推荐 */
.block, .table {
    margin: 10px auto;
}

/* 推荐 */
.block,
.table {
    margin: 10px auto;
}

尽量使用简写

/* 不推荐 */
.block {
    padding-top: 10px;
    padding-right: 20px;
    padding-bottom: 10px;
    padding-left: 20px;
}

/* 推荐 */
.block {
    padding: 10px 20px;
}

颜色使用简写的16进制色值

/* 不推荐 */
.block {
    background-color: #ffffff;
    color: #666666;
}

/* 推荐 */
.block {
    background-color: #fff;
    color: #666;
}

声明顺序规范（建议分块注释）

• 定位属性块
• 盒模型属性块
• 子元素的排版属性
• 视觉效果属性（背景色、边框等）
• 其他属性（动画、透明度等）

/* 推荐示例 */
.block {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

注释

• 避免简单的对当前类名的重申，而应该简短对功能进行描述

/* 不推荐 */
/* block--red */
.block--red {
    border: 1px solid red;
    background-color: red;
}

/* 推荐 */
/* block--red block类的红色状态，边框、背景色为红色 */
.block--red {
    border: 1px solid red;
    background-color: red;
}

• 单行注释与多行注释区分

/* 不推荐 */
/* block--red */
/* block类的红色状态，边框、背景色为红色 */
.block--red {
    border: 1px solid red;
    background-color: red;
}

/* 推荐 */
/**
 * block--red 
 * block类的红色状态，边框、背景色为红色
 */
.block--red {
    border: 1px solid red;
    background-color: red;
}

JS规范

缩进

• 使用一个制表符（两个空格）表示一个缩进

let x = 1;
let y = 2;
function add(a, b) {
    return a + b;
}
console.log(add(x, y));

分号

• 原则上表达式必须以分号结尾
  • 变量声明
  • 表达式
  • return
  • throw
  • break
  • continue
  • do-while
  • 闭包

// 变量声明
let x = 1;

// 表达式
x++;

function count(a) {
    // do-while
    do {
        a++;
    } while (a < 10);

    // return 
    return a;
}

空格

推荐在以下场合中使用空格：

• 大括号前面留一个空格
• 条件控制语句的小括号前后各留一个空格
• function参数列表小括号后留一个空格（前不留以示与条件语句区分）
• function参数列表中逗号后留一个空格
• 运算符（“+”、“-”、“/”等）前后留空格
• 注释语句块内前后各预留一个空格

// 这是注释
/* 注释语句块前后预留一个空格 */

// 函数小括号后留一个空格，多参数列表逗号后留一个空格
function totalCount(a, b) {
    let total = 0;

    // 循环条件小括号前后留一个空格
    for (let i = a; i < b; i++) {
        total += i;        
    }

    return total;
}

// 参数列表逗号后留一个空格
console.log(totalCount(1, 10));

空行

在代码中加入空行，可以提高代码的组织性和可读性，推荐在以下场合中使用空行：

• 函数块后
• 文件最后保留一个空行（版本记录优化）

function totalCount(a, b) {
    let total = 0;
    // 代码块后空行
    for (let i = a; i < b; i++) {
        total += i;        
    }
    return total;
}

// 函数后空行

console.log(totalCount(1, 10));
// 文件最后空行

换行

• 代码块的大括号换行
• 函数调用后换行

// 函数大括号换行
function test() {
   ... 
}

// 函数调用后换行
test();
test();

引号

• 使用单引号
• 变量拼接推荐使用模版字符串

const name = 'Jack';
const age = 20;

const sayHello = function (name, age) {
    return `hello, i am ${name}, my age is ${age}`;
}

逗号

• 避免不必要的逗号
  • 数组的最后一位
  • 对象的最后一位
  • ...

/* 不推荐 */
const obj = {
	name: 'name',
  age: 12,
}

/* 推荐 */
const obj = {
	name: 'name',
  age: 12
}

注释

1、单行注释

• 注释单独成行，并且上方预留一空行（首行除外）
• 双斜线后必须留一个空格
• 缩进与下一行代码保持一致
• 推荐使用 “// FIXME:” 标记问题
• 推荐使用 “// TODO:” 标记已有方案但是为实现的代码块

// 变量声明(预留空格)
let a = 1;

function caculate() {
    // FIXME: 这儿不应该使用全局变量
    total = 0;

    return total;
}

function caculate(total) {
    // TODO: 须对total进行整型或浮点型验证
    total += 1;

    return total;
}

2、多行注释

最少三行“*”后跟一个空格，具体参照下方代码中的格式进行书写

建议以下情况使用：

• 难于理解的代码段
• 可能存在错误的代码段
• 浏览器特殊HACK代码
• 业务逻辑相关的代码注释

/*
 * 这段代码完成了一个很复杂的功能，balabalabala...
 */
for (let i = 0; i < 10; i++) {
    ...
}

3、文档注释

各类标签 @param，@method等请参考useJSDoc以及JSDocGuide，建议在以下情况下使用：

• 所有常量
• 所有函数
• 所有类

/**
 * @func 
 * @desc 一个多参数函数
 * @param {string} a - 参数a
 * @param {number} b=1 - 参数b默认值1
 * @param {string} c - 参数c有三种取值方式'green'\'red'\'blue'
 * @param {object} d - 参数d是一个对象
 * @param {string} d.x - 参数d的属性x
 * @param {number} d.y - 参数d的属性y
 * @param {number} e - 参数e是一个可选参数
 */
function multiFunc(a, b = 1, c, d, e) {
    ...
}

变量声明

• 使用const和let关键字声明变量，不要使用var
• 普通变量和函数命名统一采用小驼峰，类名使用大驼峰
• 常量/枚举全大写，使用下划线分词
• 构造函数，首字母大写
• 变量声明放在作用域顶部

// const可用于声明常量和只读变量，常量全大写
const PI = 3.141592654;
const id = this.id

// let声明局部变量，小驼峰
let testVar = 1;

// 枚举类型（模拟）-全大写-下划线分词
const SEX_MODE = {
    MALE: 0,
    FEMALE: 1
}


// 类名-构造函数-首字母大写
class React {
    constructor() {
        ...
    }
    ...
}

条件判断及循环

• 能使用对象、数组、字符串所拥有的默认遍历函数解决的问题，尽量不要使用循环以及条件判断语句
• 对于超过3个以上的if - else if - else语句，使用switch case来替代
• 避免出现死循环

let arr = [1, 2, 3];
for (let i = 0; i < arr.length; i++) {
    console.log(i);
}
// 可以直接使用数组默认遍历方法
arr.forEach((item) => {console.log(item)})；

if (color === 'green') {
    ...    
} else if (color === 'red') {
    ...
} else if (color === 'blue') {
    ...
}

// 可以写成
switch(color) {
    case 'green':
        ...
        break;
    case 'red'
        ...
        break;
    case 'blue':
        ...
        break;
    ...
}

比较运算符

• 使用全等判断
• 非空判断用简写

let arr = [...];

// 使用全等判断
if (arr[0] === 'Hello World!') {
    ...
}

// 简写
if (arr.length) {
    ...
}

函数

• 使用箭头函数代替匿名函数的写法
• 必传参数放参数列表前部，可选参数放后面

// 参数列表-默认值
function delay(callback, time = 1000) {
    //匿名函数 => 箭头函数
    setTimeout(() => {
        callback('delay');
    }, time);
}

// 必传参数放前面，可选参数放最后，解构获取相应参数
function setProfile(id, name, { alias, sex, age, ...otherOptions }) {
    ...
}

解构赋值及扩展运算符

• 使用结构赋值读取对象中的参数
• 使用解构赋值读取数组内容
• 使用扩展运算符进行数组复制等

// 字面量创建数组
let arr = [1, 2, 3, 4, 5];

// 扩展运算符，数组复制
let arrSpec = [...arr];

// 解构获取数组元素内容
let [x, ...other] = arr;

函数式及面向对象

• 避免流程式编程，当前业务模块内的公共方法可以提取出来放到当前js文件的上部，在业务代码中调用
• 对于整个项目的公共方法（例如：时间格式化）等，应该提取到公共的utils文件夹中，方便其他同学统一调用

async、await

• 异步方法建议封装成promise，方便同步调用，避免回调地狱

不必要的运算及空白代码

• 如果某个值是固定的，则不需要使用
  • 诸如 !this.xx.xx 来进行重新赋值
• 空白代码、内部无操作的代码删除
  • 例如：没有用到的生命周期等

log代码及调试

• 原则上提交前删除所有console.log代码，保持线上代码整洁，需要做测试的时候再手动添加

图片管理

1、本地图片

• 本地图片在不影响展示的前提下提前做好一定的压缩处理
• 本地图片统一存放在src目录下的images文件夹中
• 本地图片命名格式： 模块 + ‘-’ + 功能
  • 例如：home-logo.jpg

2、图片链接

• 图片链接将域名抽离，方便后期维护

vue语法

class

• 对于依赖某变量来判断是否有某个class的判断语句
  • 避免写成 {{ true ? 'actived' : '' }}
  • 应该简写 {{ { actived: true } }}

组件抽象

• 当前模块可复用的组件，抽象至当前模块文件夹下的components文件夹内
• 公共复用组件，抽象至公共src目录下的components文件夹内
• 组件文件夹命名方式以 xxx-xxx 来命名，'-'连接
• 组件内的prop必须指定类型

公共方法提取

• 公共方法按类型分类提取至src目录下的utils文件夹下
• 命名方式以‘-’连接
• 公共方法若为计算、格式化类型的函数，建议写单元测试

公共样式提取

• 公共样式可提取至src目录下的style文件夹内