大连首闻grid二次开发增强文档

时间：2022-03-29 17:52:58
1. github直通车：zoGrid
2. 说明：

本插件基于大连首闻grid所做的二次开发，原生支持rest增删改查，并支持配置型增删改查。包括大量可定制可配置功能，开发的过程已经设想了非常多实际使用可能会遇到的场景，一一得到了适配，相信基本上已经可以满足大部分使用需求了，当然会有考虑不周的地方，之后也将继续在使用中对所有不足之处跟紧更新。在此感谢大连首闻grid做出的贡献。

3. 表格截图
  • 自定义按钮：
    大连首闻grid二次开发增强文档
  • 自定义工具：
    大连首闻grid二次开发增强文档
  • 编辑新增的表单验证：
    大连首闻grid二次开发增强文档
  • 新增数据：
    大连首闻grid二次开发增强文档
  • 删除行：
    大连首闻grid二次开发增强文档
  • 搜索：
    大连首闻grid二次开发增强文档
  • 排序：
    大连首闻grid二次开发增强文档
  • 导入excel：
    大连首闻grid二次开发增强文档
  • 导出excel：
    大连首闻grid二次开发增强文档
  • 编辑：
    大连首闻grid二次开发增强文档
4. 二次开发内容说明

二次开发着重点在于ajax分页加载数据功能的大量强化

  • 删除高级查询，保留其它所有特性
  • 改变工具栏刷新逻辑：
    • 原版：只要执行过一次快速查询，不管怎么刷新呈现的数据都是快速查询的内容，除非将快速查询内容清空。
    • 现版：刷新不带快速查询条件，得到表格载入时的原数据。
  • 修改默认语言为中文
  • 修改排序逻辑：
    • 原版：排序仅对当前页的数据有效，非全局
    • 现版：排序为服务器全局排序
  • 修正排序逻辑：原版在服务器获取到数据时本地依然会按照规则进行一次排序，有些情况下反而会打乱原排序。直接删除本地排序。
  • 增加自定义工具栏
  • 增加删除、编辑两颗默认可配置按钮，增加自定义按钮。
  • 增加导入excel功能
  • 大量修改与后端的交互逻辑：
    • 原版：限制后端必须接收grid规定的数据类型才能完成查找导出等交互，也即后端必须适配前端。
    • 现版：大量高*度可配置的交互逻辑，原版具有的加载、查找、导出均支持配置，服务端返回的数据，分页等格式默认并支持配置，也即前端可以适配后端。
  • 补充增、删、改三个逻辑。
  • 原版支持restful(java - spring data rest)风格交互，默认操作逻辑具有一定程度的可适配性，尽可能的不需要逻辑配置。
  • 支持复杂列加载模式，支持列数据懒加载
5. 详细配置：

gridOption与原版不同的配置项:

loadURL : '',
curdURL : {
    retrieve : "/getUsers",
    update : "updateUsers/{id}",
delete : "deleteUsers/{id}",
    create : "addUsers"
},
dataPath : "_embedded.users",
pagerPath : "page",
pagerDetailPath : {
    pagerRootPath : "page",
    page : "number",
    size : "size",
    totalElements : "totalElements",
    totalPages : "totalPages",
    firstPage : 0
},
tools : 'newData|refresh|fastQuery|export[excel,csv,pdf,txt]|importExcel',
customTools : [{
    icon: "fa fa-check",
    title: "自定义工具1图标来自内置的fontawesome",
    callback: function(data){
        alert("当前页数据集："+JSON.stringify(data));
    }
},{
    icon: "glyphicon glyphicon-plus",
    title: "自定义工具2图标来自bootstrap"
}],
exportURL : '/export',
importURL : '/import',
importAction : "none",
fastQueryURL : "/users/search/default"

配置项详细说明：

  • loadURL：优先级低于curdURL，设置loadURL主要用于rest风格，增删改查将会自动根据此url进行配置，包括各自的请求路径和请求方式(get、patch、post、delete)。当curdURL被配置时，此项无效。详细：
 + 删除：delete -> loadURL/资源id
 + 修改：patch -> loadURL/资源id
 + 查询：get -> loadURL
 + 增加：post -> loadURL
  • curdURL：配置型增删改查，需要配置增删改查四个url，发送请求时，查删为get请求，改增为post请求。路径支持”{id}”的路径匹配，{id}在解析时将会被置换为资源id。详细：
 + 删除：get -> curdURL.delete?id=资源id。
 + 修改：post -> curdURL.update?id=资源id
 + 查询：get -> curd.retrieve
 + 增加：post -> curdURL.create
  • dataPath：返回的数据详细路径，支持”.”分级，例如服务端返回的数据格式如下：
{
  "_embedded" : {
 "users" : [ ]
},
  "_links" : {
 "self" : {
 "href" : "http://localhost/users/search/default?name=%E5%A4%A7%E8%A1%97%E4%B8%8A&sex=1&size=10&page=0"
}
},
  "page" : {
 "size" : 10,
 "totalElements" : 0,
 "totalPages" : 0,
 "number" : 0
}
}

则需要设置dataPath为"_embedded.users", 默认为spring mvc的Page类返回形式："content"

  • pagerPath：分页数据详细路径，支持"."分级，要求拥有size、totalElemnts、totalPages、number四个字段，并且number（当前页）页码下标从0开始。如果字段不匹配则本配置会出错，限制性较高。例如上述数据，pagerPath应当设置为"page"。优先级低于*度更高的pagerDetailPath。

  • pagerDetailPath：本项被配置，则pagerPath无效。可配置项如下

pagerRootPath : "page",    //相当于pagerPath，为四个字段的所在路径

//分别设置四个字段与所在路径下的哪个字段匹配
page : "number",
size : "size",
totalElements : "totalElements",
totalPages : "totalPages",

firstPage : 0    //第一页下标从0或是1开始

  • tools增加了newData（新增数据）和importExcel（导入excel）两项。

    • newData：映射gridColumn内的newData属性，为true则允许新增数据时设值。
    • importExcel：导入excel，表格所作的逻辑仅为传输选择的excel到后端，至于拿取到excel做何逻辑处理则由开发人员自定。点击效果：弹出文件选择框，可多文件，xls、xlsx两种格式限制，ajax形式传输name=files二进制数据至后端，为了方便后端判断导入动作，还会传输一个表单类型的数据action=”none”（可配置），可能用于后端设定统一导入入口，并根据action选择导入动作的情景。后端需具备读取文件表单字段混合上传的能力。

  • customTools：自定义工具栏，为一个json数组，每一项代表一个工具位，工具为可配置项有

icon : "glyphicon glyphicon-plus", //支持grid依赖的fontawesome图标，也支持bootstrap的内置图标，直接添加类名即可。形式如上述配置。
title : "鼠标移动到工具位上显示文字",
callback : function(data){
//工具点击回调处理函数，传入当前页显示的数据集
}
  • exportURL：导出，支持的类型有excel、txt、pdf、csv，前端所实现的逻辑仅为传输导出意图到后端，其中包括：
//是否导出全部，为false时，导出范围参考page和size两个字段
exportAllData:false
//导出的列及其顺序
exportColumns:["name", "age", "sex", "birthday"]
//导出的文件名
exportFileName:"用户列表"
//导出的文件类型
exportType:"excel"
page:0
size:10
  • importURL：导入excel的交互地址，详细参看第六条
  • fastQueryURL：快速查询的交互地址，前端将会发送get请求以及用户的查询条件到该地址，支持的查询项映射gridColumn中的fastQuery=true，用户空缺的查询条件反应到地址上的条件值也将空缺，条件名不会空缺。例如：配置可查询项name和address，表格将提供两个项用于用户的查询，当用户只填写name时，地址为fastQueryURL?name=填写的值&address=&page=0&size=10，查询时分页操作依然有效。

gridColumn与原版不同的配置：

var sex = {1:"男",2:"女"};
var gridColumns = [
    {id:'name', title:'用户姓名', type:'string',validate:'name', columnClass:'text-center',newData:true, fastQuery:true},
    {id:'password', title:'密码', type:'string',validate:/^\d{6,16}$/, columnClass:'text-center',newData:true},
    {id:'confirmPassword',hide:"true", title:'确认密码', type:'string',validate:/^\d{6,16}$/, equalWith:"password", columnClass:'text-center',newData:true},
    {id:'sex', title:'性别', type:'string',codeTable:sex, equalWith:"age", columnClass:'text-center',newData:true, fastQuery:true},
    {id:'birthday', title:'生日', type:'date',validate:"required",validateText:"生日信息必填", format:'yyyy-MM-dd hh:mm:ss',newData:true, columnClass:'text-center'},
    {id:'vip', title:'会员类型', loadConfig:{
        resourcePath:"vip",
        resourceFrom:"_links.vip.href",
        id:"_links.self.href",
        show:"vipName",
        resourceSetUrl:"/vips>_embedded>vips"
    }, codeTable:sex, validate:"identity", type:'string', columnClass:'text-center',newData:true, fastQuery:true},
    {type:"controll",columnClass:'text-center',edit_btn:true,del_btn:true,custom_btn:[{
    text : "通过",
    style_class : "btn btn-xs btn-success",
    icon: "fa fa-check",
    callback : function(record, i){
        alert("传入当前行record和当前行所在当前页数据集的索引");
    }
},{
    text : "拒绝",
    style_class : "btn btn-xs btn-primary"
}]}
];

配置项详细说明：

  • validate ： 用于编辑和新增时的表单验证。newData没有配置为true时该字段不支持新增和编辑，也就谈不上表单验证。内置支持的表单验证类型包括：
code：        //4-8位数字
name：        //中文2-4个
identity：    //严格的身份证号码
tel：         //手机号码
email：       //邮箱
password：    //6-16位密码
required：    //非空

直接设置validate为对应验证类型字符串即可，例如：validate=”code”。同时支持自定义类型的正则，例如：validate=/^d{1,10}$/。验证出错时用户会得到两个反馈，出错项边框变红，弹出验证错误类型的对应提示信息。

  • validateText：既然验证出错有提示信息，那么提示信息自然是可自定义的。

  • newData：该列是否支持新增和编辑。

  • equalWith：该列值必须与目标值验证时必须一致。常用于密码确认情景。编辑时将自动填充为目标值。如果是密码。

  • type支持更多类型：

    • controll：此列为按钮组，不需要配置id。内部提供两颗默认按钮：edit_btn和del_btn，并默认绑定好修改、删除的逻辑。可配置自定义的实现逻辑，对应的配置字段为edit_function和del_function，将回调传入当前行的record以及所在当前页数据集的索引。
    • password：此列在新增或者编辑时，输入框类型为密码型。

  • custom_btn：自定义按钮。为一个数组json。详细如下

custom_btn:[{
    text : "通过",  //按钮显示文本
    style_class : "btn btn-xs btn-success",  //按钮样式class，默认值
icon: "fa fa-check",  //按钮文本前图标，默认为"fa fa-check"
    callback : function(record, i){
//按钮点击回调函数
        alert("传入当前行record和当前行所在当前页数据集的索引");
    }
},{
    text : "拒绝",
    style_class : "btn btn-xs btn-primary"
}]
  • loadConfig：列加载模式配置，提供五个配置项（除原表格的自定义解析外额外提供的第二种非直接加载方式）
    • resourcePath：适用于该列所有信息已经包含在该行数据里的场景，提供一个路径定位到该资源，支持.分级。优先级高于resourceFrom。
    • resourceFrom：适用于该列数据被归为一个链接放入该行数据的场景，将请求该链接获取资源，配置的一个定位到该链接的路径，支持.分级。
    • id：当使用列懒加载模式时，该列的所有数据被指向一个地址，此时id用于指向该地址的路径，当使用列急加载模式时，id用于指向该列数据的匹配key。在构建编辑、新增json时将会结合列的id属性使用。急加载模式匹配key作为option控件的value值，懒加载模式地址作为option控件的value值。
    • show：该列所要显示的内容相对于资源的路径。除了表格展示用于替换id显示时，也将在新增、编辑时作为option控件的其中一个select内容显示。
    • resourceSetUrl：资源集url，该链接在新增、编辑时将被加载用于构造一个option控件。链接后接 > 可逐级定位资源集实际路径。更多策略反映在URL的自身能力上，例如实例配置中，

      resourceSetUrl:"/vips>_embedded>vips"

      实际资源请求链接为”/vips”，资源集定位在返回json的”_embedded>vips”路径下，如果需要分页排序，则首先要求链接本身支持分页排序，并在链接上体现：”/vips?size=100>_embedded>vips”。
      详细举例说明：
 "demoes" : [ {
"id" : 4,
"name" : "陈木鑫",
"identity" : "441522xxxxxxxxxxx",
"password" : "123",
"expiredTime" : "2016-09-30 10:25:20",
"_links" : {
"self" : {
"href" : "http://localhost/demoes/4"
        },
"demo" : {
"href" : "http://localhost/demoes/4"
        },
"vip" : {
"href" : "http://localhost/demoes/4/vip"
        }
      }
    }]
{
  "id" : 2,
  "vipName" : "普通会员",
  "vipPrice" : 2000.0,
  "_links" : {
 "self" : {
 "href" : "http://localhost/vips/2"
},
 "vip" : {
 "href" : "http://localhost/vips/2"
}
}
}
 {
  "_embedded" : {
 "vips" : [ {
 "id" : 1,
 "vipName" : "超级会员",
 "vipPrice" : 5000.0,
 "_links" : {
 "self" : {
 "href" : "http://localhost/vips/1"
},
 "vip" : {
 "href" : "http://localhost/vips/1"
}
}
}, {
 "id" : 2,
 "vipName" : "普通会员",
 "vipPrice" : 2000.0,
 "_links" : {
 "self" : {
 "href" : "http://localhost/vips/2"
},
 "vip" : {
 "href" : "http://localhost/vips/2"
}
}
} ]
},
  "_links" : {
 "self" : {
 "href" : "http://localhost/vips"
},
 "profile" : {
 "href" : "http://localhost/profile/vips"
}
},
  "page" : {
 "size" : 1000,
 "totalElements" : 2,
 "totalPages" : 1,
 "number" : 0
}
}
id:"vip",
loadConfig : {
resourceSetUrl:"/vips?size=1000>_embedded>vips"
}

列本身的id原本用于数据集字段取值，但存在loadConfig时，它通常没有直接的意义，但可以用于复杂加载模式时编辑新增的回传：
例如以上demoes/4资源的vip为vips/2，需要将其更改为vips/1，那么需要传入服务端的数据，懒加载模式：

{
id:4,
 vip:"http://localhost/vips/1"
}

急加载模式：

{
id:4,
 vip:{
 id:1
}
}

其中vip字段即取自列配置的id值，表格内部已经帮助实现了细节，在表格初始化编辑、新增页面时，复杂加载列会被处理为一个下拉选择组件，每一项的值就是对应的地址或者匹配key的value，显示内容就是所配置的loadConfig.show项。
大连首闻grid二次开发增强文档
标签：

相关文章