FS平台前端设计说明v1.00

传送门： SpringBoot+SpringCloud搭建一款企业级开源基础平台

1. 概述

FS平台web前端架构以下简称fs-web，fs-web是基于开源框架layui开发。layui（谐音：类UI) 是一款采用自身模块规范编写的前端 UI 框架，遵循原生 HTML/CSS/JS 的书写与组织形式，门槛极低，拿来即用。其外在极简，却又不失饱满的内在，体积轻盈，组件丰盈，从核心代码到 API 的每一处细节都经过精心雕琢，非常适合界面的快速开发。

2. 参考资料

layui官方网站：https://www.layui.com/

3. 开发规范

文件名称统一用英文字母、数字和下划线的组合，其中不得包含汉字、空格和特殊字符；html、css、js文件字符集统一设置为utf-8；详细请查看官网。

• html规范

  属性 描述
  lay-skin=" " 定义相同元素的不同风格，如checkbox的开关风格
  lay-filter=" " 事件过滤器。你可能会在很多地方看到他，他一般是用于监听特定的自定义事件。你可以把它看作是一个ID选择器
  lay-submit 定义一个触发表单提交的button，不用填写值

Layui在解析HTML元素时，必须充分确保其结构是被支持的。你如果改变了结构，极有可能会导致该功能失效。所以在嵌套HTML的时候，你应该细读各个元素模块的相关文档。Tab选项卡为例：

<div class="layui-tab">
  <ul class="layui-tab-title">
    <li class="layui-this">标题一</li>
    <li>标题二</li>
    <li>标题三</li>
  </ul>
  <div class="layui-tab-content">
    <div class="layui-tab-item layui-show">内容1</div>
    <div class="layui-tab-item">内容2</div>
    <div class="layui-tab-item">内容3</div>
  </div>
</div>

• css规范

class命名前缀：layui，连接符：-，如：class=“layui-form”

命名格式一般分为两种：一：layui-模块名-状态或类型，二：layui-状态或类型。因为有些类并非是某个模块所特有，他们通常会是一些公共类。如：一（定义按钮的原始风格）：class=“layui-btn layui-btn-primary”、二（定义内联块状元素）：class=“layui-inline”

从CSS 样式代码插入的形式来看基本可以分为以下3种：内联式、嵌入式和外部式三种。html代码中不建议用嵌入式。

3.1 全局配置

你可以在使用模块之前，全局化配置一些参数，尽管大部分时候它不是必须的。所以我们目前提供的全局配置项非常少，这也是为了减少一些不必要的工作，尽可能让使用变得更简单。目前支持的全局配置项如下：

layui.config({
  dir: '/res/layui/' //layui.js 所在路径（注意，如果是script单独引入layui.js，无需设定该参数。），一般情况下可以无视
  ,version: false //一般用于更新模块缓存，默认不开启。设为true即让浏览器不缓存。也可以设为一个固定的值，如：201610
  ,debug: false //用于开启调试模式，默认false，如果设为true，则JS模块的节点会保留在页面
  ,base: '' //设定扩展的Layui模块的所在目录，一般用于外部模块扩展
})

3.2 定义模块

方法：layui.define([mods], callback)

通过该方法可定义一个 Layui模块。参数mods是可选的，用于声明该模块所依赖的模块。callback即为模块加载完毕的回调函数，它返回一个exports参数，用于输出该模块的接口。

layui.define(function(exports){
  //do something
  
  exports('demo', function(){
    alert('Hello World!');
  });
});

exports是一个函数，它接受两个参数，第一个参数为模块名，第二个参数为模块接口，当你声明了上述的一个模块后，你就可以在外部使用了，demo就会注册到layui对象下，即可通过 layui.demo() 去执行该模块的接口。

你也可以在定义一个模块的时候，声明该模块所需的依赖，如：

layui.define(['layer', 'laypage'], function(exports){
  //do something
  
  exports('demo', function(){
    alert('Hello World!');
  });
});

上述的[‘layer’, ‘laypage’]即为本模块所依赖的模块，它并非只能是一个数组，你也可以直接传一个字符型的模块名，但是这样只能依赖一个模块。

3.3 加载所需模块

方法：layui.use([mods], callback)

Layui的内置模块并非默认就加载的，他必须在你执行该方法后才会加载。它的参数跟上述的 define方法完全一样。
另外请注意，mods里面必须是一个合法的模块名，不能包含目录。如果需要加载目录，建议采用extend建立别名（详见模块规范）

layui.use(['laypage', 'layedit'], function(){
  var laypage = layui.laypage
  ,layedit = layui.layedit;
  
  //do something
});

3.4 加载所需模块

方法：layui*.link(href)*

href即为css路径。注意：该方法并非是你使用Layui所必须的，它一般只是用于动态加载你的外部CSS文件。

3.5 本地存储

本地存储是对 localStorage 和 sessionStorage 的友好封装，可更方便地管理本地数据。

localStorage 持久化存储：layui.data(table, settings)，数据会永久存在，除非物理删除。

sessionStorage 会话性存储：layui.sessionData(table, settings)，页面关闭后即失效。

上述两个方法的使用方式是完全一样的。其中参数 table 为表名，settings是一个对象，用于设置key、value。下面与 layui.data 方法为例：

//【增】：向test表插入一个nickname字段，如果该表不存在，则自动建立。
layui.data('test', {
  key: 'admin'
  ,value: '码农洞见'
});
 
//【删】：删除test表的nickname字段
layui.data('test', {
  key: 'admin'
  ,remove: true
});
layui.data('test', null); //删除test表
  
//【改】：同【增】，会覆盖已经存储的数据
  
//【查】：向test表读取全部的数据
var localTest = layui.data('test');
console.log(localTest.admin); 

3.6 Layui如何使用内部的jQuery

由于Layui部分内置模块依赖jQuery，所以我们将jQuery1.11最稳定的一个版本作为一个内置的DOM模块（唯一的一个第三方模块）。只有你所使用的模块有依赖到它，它才会加载，并且如果你的页面已经script引入了jquery，它并不会重复加载。内置的jquery模块去除了全局的$和jQuery，是一个符合layui规范的标准模块。所以你必须通过以下方式得到：

//主动加载jquery模块
layui.use(['jquery', 'layer'], function(){ 
var $ = layui.$ //重点处
,layer = layui.layer;

//后面就跟你平时使用jQuery一样
$('body').append('hello jquery');
});

//如果内置的模块本身是依赖jquery，你无需去use jquery，所以上面的写法其实可以是：
layui.use('layer', function(){ 
var $ = layui.$ //由于layer弹层依赖jQuery，所以可以直接得到
,layer = layui.layer;

//……
});

3.7 扩展Layui模块

layui提供的模块有时可能还无法满足你，或者你试图按照layer的模块规范来扩展一个模块。那么你有必要认识layui.define()方法，相信你在文档左侧的“底层方法”中已有所阅读。下面就就让我们一起扩展一个Layui模块吧：

第一步：确认模块名，假设为：mymod，然后新建一个mymod.js 文件放入项目任意目录下（注意：不用放入layui目录）

第二步：编写test.js 如下：

/**
  扩展一个test模块
**/      
 
layui.define(function(exports){ //提示：模块也可以依赖其它模块，如：layui.define('layer', callback);
  var obj = {
    hello: function(str){
      alert('Hello '+ (str||'mymod'));
    }
  };
  
  //输出test接口
  exports('mymod', obj);
});    

第三步：设定扩展模块所在的目录，然后就可以在别的JS文件中使用了

//config的设置是全局的
layui.config({
  base: '/res/js/' //假设这是你存放拓展模块的根目录
}).extend({ //设定模块别名
  mymod: 'mymod' //如果 mymod.js 是在根目录，也可以不用设定别名
  ,mod1: 'admin/mod1' //相对于上述 base 目录的子目录
});
 
//你也可以忽略 base 设定的根目录，直接在 extend 指定路径（主要：该功能为 layui 2.2.0 新增）
layui.extend({
  mod2: '{/}http://cdn.xxx.com/lib/mod2' // {/}的意思即代表采用自有路径，即不跟随 base 路径
})
 
//使用拓展模块
layui.use(['mymod', 'mod1'], function(){
  var mymod = layui.mymod
  ,mod1 = layui.mod1
  ,mod2 = layui.mod2;
  
  mymod.hello('World!'); //弹出 Hello World!
});

3.8.接口规范说明

3.8.1.规范原则

• 接口返回数据即显示：前端仅做渲染逻辑处理；
• 渲染逻辑禁止跨多个接口调用；
• 前端关注交互、渲染逻辑，尽量避免业务逻辑处理现象；

3.8.2.数据格式

• 响应数据格式

  {
  “code”: 200, //请求处理状态
  “msg”: “success”, //请求处理消息
  “url”: null, //请求地址
  “count”: 2,
  “data”: [{}, {}…]
  }

code：请求处理状态

 * 100 ERROR： 代码异常

 * 200 OK：服务器成功返回用户请求的数据

 * 201 CREATED ：用户新建或修改数据成功。

 * 202 Accepted：表示请求已进入后台排队。

 * 400 INVALID REQUEST ：用户发出的请求有错误。

 * 401 Unauthorized ：用户没有权限。

 * 403 Forbidden ：访问被禁止。

 * 404 NOT FOUND ：请求针对的是不存在的记录。

 * 406 Not Acceptable ：用户请求的的格式不正确。

 * 500 INTERNAL SERVER ERROR ：服务器发生错误。

4. 组件说明

4.1 表格

table 组件默认规定的数据格式为：

{
  "code": 0,
  "msg": "",
  "count": 1000,
  "data": [{}, {}]
}

如果你想重新规定返回的数据格式，那么可以借助 response 参数，如：

table.render({
  elem: '#demp'
  ,url: ''
  ,response: {
    statusName: 'status' //规定数据状态的字段名称，默认：code
    ,statusCode: 200 //规定成功的状态码，默认：0
    ,msgName: 'hint' //规定状态信息的字段名称，默认：msg
    ,countName: 'total' //规定数据总数的字段名称，默认：count
    ,dataName: 'rows' //规定数据列表的字段名称，默认：data
  } 
  //,…… //其他参数
});

用于对分页请求的参数：page、limit重新设定名称，如：

table.render({
  elem: '#demp'
  ,url: ''
  ,request: {
    pageName: 'curr' //页码的参数名称，默认：page
    ,limitName: 'nums' //每页数据量的参数名，默认：limit
  }
  //,…… //其他参数
});

最后的最后

为初学者提供学习指南，为从业者提供参考价值。我坚信码农也具有产生洞见的能力。扫描下图二维码关注，学习和交流！