梅斯 web前端规范

web前端开发

一、 目录结构规范

1. 后台框架项目结构

+ app
    + demo                     // 组件测试代码
    + static                  //静态手写的文件代码
        + js
            config.js         //项目配置文件
            common.js         //公共的js
        + css
            + scss            //sass样式
                _config.scss  //scss公共函数和参数
                style.scss
            + less            //不推荐使用less
                style.less
            //如果使用scss或者less 则css的文件名称随相关文件一致就可以
            basic.css         //基础的css
        + images              //所有需要用到的项目图片
            + icon
            + bg
            + banner
            + logo
        + html               //各个功能页面
            main.html
    + docs                     // 项目描述文档
    + src
        + plugins                   //插件
            + plugins-name
                - css
                - ...
        + themes                   //主题文件
            + default
                - js
                - images
                  style.css
        + local                   //语言包
            + zh_CN
                local_zh-CN.js
      index.html             //项目入口
      app.js                 //项目js入口
      readme.md              //项目文件描述文件

2. H5 APP项目

// 这里习惯使用yaoman之类的构建工具生成，同时也限制与一些主流的app web ui 框架已经写好结构的问题，所以暂时不做说么，等待相关app ui框架完全确定后在进行实际的约束

3. iframe框架项目结构

为了保证每次iframe中相关公共资源的加载小，所以需要把相关针对页面的资源拆分，各个页面根据需要加载相关资源
主要针对js和css拆分。

二、 文件资源命名规范

1. 文件和文件名约束

都只允许使用小写字母命名单词与单词之间用中横线分隔

//名称格式［页面名称］.js
index.js
//[页面名称]－[功能类型].css
//当然如果公共的css就直接使用[功能类型].css
index-layout.css
//[页面名称].html
//如果是某个页面中的某个功能则：[页面名称]－[功能].html
//如果是公共通用的页面则：[功能].html
userinfo-modal.html
//图片的命名和其他的相反，[功能类型]-[名称].png/jpg
logo.png
icon-like.png

三、 开发环境规范

在开发中，可能涉及到大量的 ajax 操作，所以推荐使用服务器环境开发，但是同时需要保证在非服务器环境下资源引用也是正确的（这里涉及到的是引用资源时候使用的是 绝对路径 和 相对路径 的问题.

推荐服务器环境使用 nodejs 生成
方法：
1. 安装 nodejs
2. npm install -g anywhere
3. 在项目目录下通过命令行工具执行：
anywhere port[这里是端口号，如果：4000/8080等]
---
当然这里更推荐使用 gulp / grunt / webpack 直接生成服务器环境

四、编码规范

前端编码规范可参考 Bootstrap 规范执行，里面内容过为详细，这里只对差异点进行说明

1. HTML 编码规范

• HTML 文档头使用 HTML5 doctype 规范编辑，不使用 HTML4.0.1 的形式或其他低版本形式

• 语法空格不做强制要求，无论Tab 或者 空格 的形式都能允许

• 不强制要求style标签和javascript标签的引用位置

• HTML 功能模块需要有注释代码,如下：

<!-- warp start -->
<div class="warp"></div>
<!-- warp end / content start -->
<div class="content"></div>

2. CSS 编码规范

• 不允许style代码写入HTML中，除非插件处理生成的代码片段
• 在开发css的时候，对于公共组件代码需要使用 ms- 命名空间约束

<div class="ms-modal">
    <div class="ms-modal-bg"></div>
    <div class="ms-modal-body">
        <div class="ms-modal-title"></div>
        <div class="ms-modal-content"></div>
    </div>
</div>

• css样式和属性都应该使用小写字母进行编辑并且属性和值之间需要有一个空格位，比如颜色值

//错误的写法
color: #FFF;
//正确的写法
color: #fff;

• 不允许使用 !important强制覆盖样式,对于需要样式层叠覆盖的，只能通过增加权重的方法去出来

HTML:
<div class="warp">
    <h1>这里是标题</h1>
</div>
============================
CSS:
h1{font-size: 12px;}
//错误的写法
h1{font-size: 16px !important;}
//正确的写法
.warp h1{font-size: 16px;}

• 颜色值使用十六位简写形式#fff，不用#ffffff这样的格式，也不使用rgb、hsl等写法，非透明颜色不使用rgba

• CSS每个功能模块都必须有代码注释，并且模块和模块之间需要至少一行的空隙

//modal组件
.ms-modal{}
.ms-modal .ms-modal-bg{}
...
//alert组件
.ms-alert{}
.ms-alert .ms-alert-title{}

• 避免不必要的 CSS 嵌套和过深的嵌套
  尽量保证2层作业的嵌套，这样能避免全局的css污染增加CSS的查询效率，同时方便后续样式修改的层叠。

//错误的写法
.ms-modal{}
.ms-modal .ms-modal-body{}
.ms-modal .ms-modal-body .ms-modal-title{}
//正确的写法
.ms-modal{}
.ms-modal .ms-modal-body{}
.ms-modal-body .ms-modal-title{}

3. JavaScript 编码规范

• 编写JavaScript时，因为使用jQuery插件开，所以相关方法和功能使用jQuery的方法去实现，不要javascript 方法和 jQuery方法混用

$("#"+elId) // √
document.getElementById(eleId)  // X

• 所有JavaScript代码应该写到$(document).ready(function(){})下面，保证DOM加载完成后的相关事件绑定能成功。

• 不允许使用setTimeout去执行事件延时绑定，应该改用callBack的形

• API接口式去处理全部写到config.js文件中，共方法全部写入common.js中

• 所有存在的方法都需要有方法的注释描述和方法的编写者（特别是公共的方法，需要遵循 apidocjs）的书写约束

5. jQuery 插件使用规范

• 需要保证插件的正确依赖关系
• 不直接修改插件的CSS和js内容，涉及到修改的，CSS应该当独创建新主题的形式修改，js需要使用方法重写的形式处理，对于闭包中有些方法无法重写的情况，修改源码除必须写相关的详细注释

6. 图片使用规范

• 具有透明效果的图片使用png格式,其他的使用jpg

• 对于小图标使用Sprite图片实现

五、功能组件结构

1. 组件列表

a. 时间控件

• 地址
  http://laydate.layui.com/

• 用法

laydate({
    elem: '#hello', //目标元素
    event: 'focus', //响应事件。如果没有传入event，则按照默认的click
    format: 'YYYY/MM', // 分隔符可以任意定义，该例子表示只显示年月
    festival: true, //显示节日
    choose: function(datas){ //选择日期完毕的回调
        alert('得到：'+datas);
    },
    min: laydate.now(-1), //-1代表昨天，-2代表前天，以此类推
    max: laydate.now(+1), //+1代表明天，+2代表后天，以此
    istime: false, //是否开启时间选择
    isclear: true, //是否显示清空
    istoday: true, //是否显示今天
    issure: true // 是否显示确认类推
});

b. 弹框、弹窗控件（dailog）

• 地址
  http://layer.layui.com/

• 用法

layer.open({
    type: 1, //page层
    area: ['500px', '300px'],
    title: '提示',
    shade: 0.6, //遮罩透明度
    moveType: 1, //拖拽风格，0是默认，1是传统拖动
    shift: 1, //0-6的动画形式，-1不开启
    content: '<div style="padding:50px;">这是一个非常普通的页面层（type:1），传入了自定义的html</div>'
});

c. 模板控件

• 地址
  http://laytpl.layui.com/

• 用法
  第一步：编写模版。你可以使用一个script标签存放模板，如：

<script id="demo" type="text/html">
<h1>{{ d.title }}</h1>
<ul>
{{# for(var i = 0, len = d.list.length; i < len; i++){ }}
    <li>
        <span>姓名：{{ d.list[i].name }}</span>
        <span>城市：{{ d.list[i].city }}</span>
    </li>
{{# } }}
</ul>
</script>

第二步：建立视图。用于呈现渲染结果。

<div id="view"></div>

第三步：渲染模版

var data = {
    title: '前端攻城师',
        list: [{name: '贤心', city: '杭州'}, {name: '谢亮', city: '北京'}, {name: '浅浅', city: '杭州'}, {name: 'Dem', city: '北京'}]
    };
var gettpl = document.getElementById('demo').innerHTML;
laytpl(gettpl).render(data, function(html){
    document.getElementById('view').innerHTML = html;
});

d. 下拉查询控件

• 地址
  bootstrap-suggest-plugin
• 用法
  HTML格式模板

<div class="input-group">
    <input type="text" class="form-control" id="test">
    <div class="input-group-btn">
        <button type="button" class="btn btn-default dropdown-toggle" data-toggle="dropdown">
            <span class="caret"></span>
        </button>
        <ul class="dropdown-menu dropdown-menu-right" role="menu">
        </ul>
    </div>
    <!-- /btn-group -->
</div>

javascript出发方法

 var testBsSuggest = $("#test").bsSuggest({
        url: "data.json",//url: "/rest/sys/getuserlist?keyword=",
        idField: "userId",
        keyField: "userName"
    }).on('onDataRequestSuccess', function (e, result) {
       // console.log('onDataRequestSuccess: ', result);
    }).on('onSetSelectValue', function (e, keyword, data) {
       // console.log('onSetSelectValue: ', keyword, data);
    }).on('onUnsetSelectValue', function (e) {
       // console.log("onUnsetSelectValue");
    });

六、公共代码描述和规范

1. CSS 公共代码描述

• 使用normalize.css对浏览器差异进行处理，这部分代码放置到basic.css 头部 normalize.css

2. js 公共代码描述