前端规范

基础

特别注意

项目即将本地化，所以对于使用三方类库/框架/工具的，能本地化就本地化，不能的就尽量不要使用。

文件历史

像WebStorm、PHPStorm、Atom等重量级编辑器都自带了localHistory功能，就是本地缓存文件内容。

注意

没有此功能的编辑器(sublime、vscode等)都要装个 localHistory 插件，确保在没有git的时候，文件丢失也能找到。

缩略图

页面或项目要有对应的缩略图，方便以后查找，下面是以Vue或React为例的缩略图目录结构：

_thumbnail
  ├─ css 
  ├─ js
  ├─ images
  └─ index.html

GOMS缩略图地址：http://192.168.112.34:8080/goms_html/GOMS_V4/demo/thumbnail.html

缩略图

注意

缩略图的名称要和页面名称/项目名称保持一至
尽量小而详细

命名规范

注意

所有命名最好要和功能保持一至

1、文件或目录

  • 文件目录结构
html
  ├─ css
  |  ├─ index.css
  |  └─ flight_list.css  
  ├─ images
  |  ├─ img-logo.png
  |  ├─ bg-banner.png
  |  ├─ icon-group-nav.png
  |  └─ icon-home.png  
  ├─ js
  |  ├─ index.js
  |  ├─ flight_list.js
  |  └─ vendor
  |     ├─ jquery.min.v1.1.9.js
  |     └─ echart.min.v2.0.js
  ├─ index.html
  └─ flight_list.html

如上所示，html、css及js都是以_下划线间隔的，并且是一一对应的关系。三方的框架js需要加版本号。

这里重点讲下图片的命名方式：

描述 示例
图片 img-开头 img-logo.png
图标 icon-开头 icon-home.png
图标组 icon-group-开头 icon-group-nav.png
背景图片 bg-开头 bg-banner.png
  • 目录（项目名）

大项目

├─ GOMS_HTML 
├─ ACDM_REACT
└─ ACDM_VUE

小项目

├─ flight_dynamic 
├─ process_control
└─ weather_analyze

2、class、id、name、attributes、图标及作用于js的命名

  • class（[姓名前缀]，横杠间隔）
<div 
    class="zh-flight-list"
    class="flight-list"
    >
</div>
  • id（[姓名前缀]，下划线间隔）
<div 
    id="zh_flight_list"
    id="flight_list"
    >
</div>
  • name（[姓名前缀]，下划线间隔）
<div 
    name="zh_email"
    name="email"
    name="user_name"
    >
</div>
  • attributes（data-开头）
<div 
    data-url="http://www.baidu.com" 
    data-url-search="name=tom"
    >
</div>
  • 图标（[姓名前缀]，zh-icon-开头）
<span class="zh-icon-home"></span>
  • 作用于js（class使用js-开头，id使用js_开头）
<div 
    class="js-del"
    id="js_edit"
    >
</div>

3、JS代码中的命名

  • 变量与常量（私有的以_下划线开头）
// 变量
var list = [],
    userName = 'tom', // 小驼峰命名法
    _this = this; // 私有

// 常量/全局变量
var AIRPORT = 'KMG',
    AIRPORT_ICAO = 'ZPPP', // 下划线间隔
    _LANG = 'zh'; // 私有
  • 函数命名（小驼峰命名法）
function reqFlightData() {
    // 函数体
}
  • jQuery变量
<button id="js_edit_node" type="button">编辑节点</button>

<script>
    var $editNode = $('#js_edit_node');
</script>
  • 自定义类（大驼峰命名法）
function UserProfile() {
    this.name = 'tom';
    this.score = function() {
        return 100;
    }
}
var userProfile = new UserProfile();

代码规范

1、缩进方式

不管使用4个空格(推荐)，还是2空格(三方)，都要项目内统一

function getList(res) {
    var data = res.data;
}

2、统一要有结束符(分号)

import React from 'react';
import ReactDOM from 'react-dom';
import {message} from 'antd';

function getList(res) {
    let status = res.status;
}

3、注释

  • 单行注释（加个空格）
// var name = 'tom';
  • 多行注释
/*function test() {
    // ...
}*/
  • 功能函数注释
/*
  进度条
  opts: Object* {}
  callback: Function
*/
function progressBar(opts, callback) {
  var defaultOpts = {
    percent: 0,   // Number* 进度百分比
    animate: true // Boolean 进度动画
  }
  opts = Object.assign(defaultOpts, opts);
  // ...
  if(callback) callback();
}

4、多语言与API接口地址

  • 多语言
var _LANG = {
    success: '操作成功~',
    error: '操作失败~'
}
  • API
var _API = {
    getFlightList: 'http://xxx.com/getFlightList'
}

5、文本超出省略

<!-- HTML -->
<div data-lang data-follow="2">中华人国共和国</div>

<!-- JS -->
<script src="http://res.layui.com/layui/release/layer/dist/layer.js?v=3111"></script>
<script>
$('[data-lang]').mouseover(function() {
    var follow = +this.dataset.follow || 2, // 1：上 2：右 3：下 4：左
        required = this.dataset.required;
    if (required !== undefined) { // 要求显示
        layer.tips(this.innerText, this, {tips: [follow, '#f00'], time: -1});
    } else { // 条件显示
        if (this.offsetWidth < this.scrollWidth) {
            layer.tips(this.innerText, this, {tips: [follow, '#f00'], time: -1});
        }
    }
}).mouseout(function() {
    layer.closeAll('tips');
});
</script>

<!-- CSS -->
<style>
[data-lang]{width: 80px;height: 30px;line-height: 30px;font-size: 14px;white-space: nowrap;text-overflow: ellipsis;overflow: hidden;}
</style>

文本省图

5、html和css统一使用双引号

<div class="zh-navbar"></div>

.box::after {
    content: ""
}

6、css规范

  • 类名与花括号之间要有空格
  • 冒号后面要有空格
  • 共享样式要换行
  • 颜色值能少写就少写，如#ffffff->#fff，#ff0000->#f00
.foo,
.bar {
    color: #f00;
    border: 1px solid #333;
}

7、数据源

如果开发的项目中有多个数据源，需要数据源加个注释，如下：

const API_1 = 'www.aaa.com/flight/';  // from zhangsan(A)
const API_2 = 'www.bbb.com/manage/';  // from lisi(A)
const API_3 = 'www.ccc.com/user/';    // from wanger(D)

git提交备注

项目名/模块名：修改内容描述

ACDM：航班动态修改
珠海大屏：UI及交互优化、测试修改

安全存储

如cookie、localStorage、sessionStorage等web存储

sessionStorage('uinfo', encodeURIComponent(JSON.stringify({"name": "tom", "sex": 1})));

兼容性

1、分辨率

兼容台式电脑(1920x1080)和笔记本电脑(1360x768)

多版本

index.html // 当前版本
index_v1.0.2.html // 历史最近版本
index_v1.0.1.html // 历史版本
index_v1.0.0.html // 历史初版

多项目

flight_dynamic(KMG).html
flight_dynamic(PVG).html
flight_dynamic(ZUH).html

优化

1、操作提示

  • 请求接口需要loading效果
  • 实时刷新不需要loading效果，隐式刷新就行了
  • 删除操作需要确认操作

端口号

描述 示例
本地默认 8x 80/81/82
本地使用 9x 90/91/92
本地开发 300x 3000/3001/3002
本地测试(nginx) 400x 4000/4001/4002

优化建议

大家有时间的话，多浏览下其他人的项目，必要的话，提出一些合理的改进意见，对于提出的建议没有问题的，一定抽时间完成。

我这边每周也会随机查看，当然我希望你们这边也尽量完善项目。

API文档

如果后端没条件编写API接口文档或不好沟通的，就辛苦大家先在 showdoc 编写，直接后端统一规范，这样方便自己，也方便他人。

公共文件

目录/文件存放结构

_static
  ├─ css
  |  ├─ common.css
  |  ├─ 500.css
  |  └─ bootstrap.min.css
  ├─ js
  |  ├─ vue
  |  |  ├─ vue.min.2.5.21.js
  |  |  ├─ vue-router.min.3.0.2.js
  |  └─ └─ vuex.min.3.0.1.js
  |  ├─ react
  |  |  ├─ react.min.16.6.1.js
  |  |  ├─ react-dom.min.16.6.1.js
  |  |  ├─ react-redux.min.5.1.1.js
  |  |  ├─ react-router-dom.min.4.3.1.js
  |  └─ └─ redux.min.4.0.1.js
  |  ├─ jquery.min.1.11.2.js
  |  ├─ moment.min.2.18.1.js
  |  ├─ axios.min.0.18.0.js
  |  ├─ echarts.min.3.2.2.js
  |  ├─ protobuf.js
  |  ├─ turf.min.js
  |  ├─ socketio.js
  └─ └─ common.js

在入口文件index.html，通过script/link引入，然后添加webpack配置，加个externals

示例：

index.html

<script type="text/javascript" src="%PUBLIC_URL%/jquery.min.js"></script>
<script src="https://webapi.amap.com/maps?v=1.3&key=b705b0ffe322148bbf5c1febdf47fe95&plugin=AMap.Geocoder"></script>

webpack.config.dev.js/webpack.config.prod.js

externals: {
  AMap: "AMap",
  jquery: 'jQuery'
}

就可以正常通过import使用了

import $ from 'jquery';
import AMap from 'AMap';

← 三方框架 →