jqGrid API 及用法

jqGrid 是一个用来显示网格数据的jQuery插件,文档比较全面,附带中文版本。


不知是不是官方地址,不过有像http://www.trirand.com/blog/




引用一篇文章:http://mj4d.iteye.com/blog/1628851

jqGrid是一款处理表格展现的jQuery插件,支持分页、滚动加载、搜索、锁定、拖动等一系列对表格的常规操作。以下是最近项目中实践jqGrid的整理

1、引入到项目中来

jqGrid的主页在http://www.trirand.com/blog/ ,上面提供了下载、demo、wiki等文档,都比较详尽。特别是http://www.trirand.com/jqgridwiki/doku.php 中值得开发中多多关注。好了,下载后需要在项目的头文件中引入:

Js代码   收藏代码
  1. "stylesheet" type="text/css" href="$request.contextPath/script/jqGrid/css/ui.jqgrid.css" />  

  2.  

  3.  

jqGrid采用了jQueryUI的CSS主题,需要下载相应的主题http://jqueryui.com/themeroller/ 找到相应的主题下载,如果使用了datepicker控件,还需要ui。如下:

Js代码   收藏代码
  1. "stylesheet" type="text/css" href="$request.contextPath/script/jqGrid/css/jquery-ui-1.8.22.custom.css" media="all"/>  

  2.  

  3.  

2、在页面中使用

在页面中如vm、jsp中使用,需要两个基本的元素

Js代码   收藏代码
  1. "jqGridId">
    //这个是必须的  

  2. "pager">
    //这个是显示分页bar的信息,根据需要  

然后在js中

Js代码   收藏代码
  1. $("#jqGridId").jqGrid({options})  

这样就是一个最基本的设置,重点是在这里的options上,包括基本参数设定和函数。具体可见官网的文档:

写道
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:methods

3、参数(options)

参数是指jqGrid对象中设置各种特性的属性,具体的设置在http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options

下面一个例子,罗列了常用的参数,并对参数进行了说明:

Js代码   收藏代码
  1. $("#jqGridId").jqGrid({  

  2.    url: s2web.appURL + "jq/queryWare.action",  

  3.    datatype:"local", //为local时初始化不加载,支持json,xml等  

  4.    mtype: "POST",  

  5.    colNames:['编号', '作者', 'ISBN','重量','描述'], //表头  

  6.    colModel:[ //这里会根据index去解析jsonReader中root对象的属性,填充cell  

  7.        {name:'id', index:'id', width:55, align:"center",sortable:false},  

  8.        {name:'author', index:'author', width:100, sortable:false},  

  9.        {name:'isbn', index:'isbn', width:120,align:"right", sortable:false},  

  10.        {name:'weight', index:'weight', width:80,align:"center", sortable:false},  

  11.        {name:'wareDesc', index:'wareDesc', width:400, sortable:false}  

  12.    ],  

  13.    width: 'auto', //数字 & 'auto','100%'  

  14.    height: 200,  

  15.    rowNum: 5, //每页记录数  

  16.    rowList:[5, 10,20,30], //每页记录数可选列表  

  17.    pager: '#pager2', //分页标签divID  

  18.    viewrecords: true, //显示记录数信息,如果这里设置为false,下面的不会显示 recordtext: "第{0}到{1}条, 共{2}条记录", //默认显示为{0}-{1} 共{2}条 scroll: false, //滚动翻页,设置为true时翻页栏将不显示  

  19.    /**这里是排序的默认设置,这些值会根据列表header点击排序时覆盖*/ sortable: false,  

  20.    sortname: "warename",  

  21.    sortorder: "desc",  

  22.  

  23.    caption:"商品列表", //显示查询结果表格标题  

  24.    rownumbers: true, //设置列表显示序号,需要注意在colModel中不能使用rn作为index  

  25.    rownumWidth: 20, //设置显示序号的宽度,默认为25  

  26.    multiselect: true, //多选框  

  27.    multiboxonly: true, //在点击表格row时只支持单选,只有当点击checkbox时才多选,需要multiselect=true是有效  

  28.    prmNames : { //如当前查询实体为ware,这些可以在查询对象的superObject中设定  

  29.        page: "wareDetail.page",  

  30.        rows: "wareDetail.rows",  

  31.        sort: "wareDetail.sidx",  

  32.        order: "wareDetail.sord",  

  33.        search: "wareDetail.search"  

  34.    },  

  35.    jsonReader:{ //server返回Json解析设定  

  36.        root: "list", //对于json中数据列表  

  37.        page: "page",  

  38.        total: "totalPage",  

  39.        records: "totalCount",  

  40.        repeatitems: false,  

  41.    }  

  42. });  

  43.  

  44. $("#jqGridId").jqGrid('navGrid','#pager2'{edit:false,add:false,del:false,search:false});//这里设定分页bar显示的信息  

以上各个参数的含义已经做了说明,具体可见上面文档的详细介绍。

prmNames: 这些参数每次会作为请求参数传递给server端,一般维持分页、排序等信息。可在查询对象中统一声明这些属性,与这里设置保持一致。如:

Java代码   收藏代码
  1. public class JqGridQueryBase implements Serializable {  

  2.  

  3.    private static final long serialVersionUID = -2849625318773684220L;  

  4.  

  5.    /** 当前页面 */  

  6.    private int               page;  

  7.    /** 每页的记录数 */  

  8.    private int               rows;  

  9.    /** 查询字段值 */  

  10.    private String            search;  

  11.    /** 排序字段和排序方式如:username/asc */  

  12.    private String            sidx;  

  13.    private String            sord;  

  14.  

  15.    /** 分页信息:总记录数 */  

  16.    private int               totalCount;  

jsonReader: 与prmNames一样,是与server端Json格式交互的解析方式,root元素是一个json数组,解析colModel中的元素,而其他则涉及分页等信息。比如我们在Action中每次返回的对象为PageModule,可定义为:

Java代码   收藏代码
  1. public class PageModule extends JqGridQueryBase {  

  2.  

  3.    private static final long serialVersionUID = -663611670315885315L;  

  4.    /** 查询返回结果数据 */  

  5.    private List           list             = new ArrayList();  

colModel: colModel对json数组中对象如何解析填充到表格的cell的设定,包括基本的name、index、width、formater等,具体见http://www.trirand.com/jqgridwiki/doku.php?id=wiki:colmodel_options

比如下设置:

  • name   :为Grid中的每个列设置唯一的名称,这是一个必需选项,其中保留字包括subgrid、cb、rn。

  • index   :设置排序时所使用的索引名称,这个index名称会作为sidx参数(prmNames中设置的)传递到Server。

  • label   :当jqGrid的colNames选项数组为空时,为各列指定题头。如果colNames和此项都为空时,则name选项值会成为题头。

  • width   :设置列的宽度,目前只能接受以px为单位的数值,默认为150。

  • sortable   :设置该列是否可以排序,默认为true。

  • search   :设置该列是否可以被列为搜索条件,默认为true。

  • resizable   :设置列是否可以变更尺寸,默认为true。

  • hidden   :设置此列初始化时是否为隐藏状态,默认为false。

  • formatter   :预设类型或用来格式化该列的自定义函数名。常用预设格式有:integer、date、currency、还支持custom的方式

以上个参数含义来自http://blog.csdn.net/jpr1990/article/details/6891115

比如对价格需要加前缀和分割可以如下设定:

Js代码   收藏代码
  1. {name:'price',index:'price', width:80,align:"right", formatter:'currency', formatoptions:{decimalSeparator:".", thousandsSeparator: ",", decimalPlaces: 2, prefix: "$"}},  

支持下拉select的设定:

Js代码   收藏代码
  1. {name:'valid',index:'valid', width:100,align:"center", formatter:'select',edittype:'select', editoptions:{value:"0:现货;1:可配货;2:无货"}}  

显示链接:

Js代码   收藏代码
  1. {name:'warename', index:'warename', width:300,sortable:false, formatter:'showlink', formatoptions:{baseLinkUrl:'query.action', addParam: '&action=edit'}},  

4、常用方法(methods)

http://www.trirand.com/jqgridwiki/doku.php?id=wiki:methods

jqGrid支持两种方式调用函数方法:

Java代码   收藏代码
  1. jQuery("#grid_id").jqGridMethod( parameter1,...parameterN );  

  2. jQuery("#grid_id").jqGrid('method', parameter1,...parameterN );  

下面是新的API,推荐使用新的调用方法,也支持链式调用,如:

Js代码   收藏代码
  1. jQuery("#grid_id").jqGrid('setGridParam',{...}).jqGrid('hideCol',"somecol").trigger("reloadGrid");  

1、新增{rowid, data, position(first、before、last、after)}

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid("addRowData", "1" ,{'name':'zhangsan', 'age': 20}, "first" );  

2、清空grid

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid("clearGridData");    

3、返回当前grid序号

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid('getDataIDs');  

4、根据rowID获取当前row的值

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid('getRowData', rowIds[i]);  

5、设置某row值

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid('setRowData', rowIds[i], {});  

一个例子:需要对grid中的数据进行循环遍历获取、设置、更改
Js代码   收藏代码
  1. var rowIds = $("#jqGrid_id").jqGrid('getDataIDs');  

  2. if(rowIds){  

  3.    for(var i = 0, j = rowIds.length; i < j; i++) {  

  4.        var curRowData = $("#jqGrid_id").jqGrid('getRowData', rowIds[i]);  

  5.        //curRowData = {"name1":"value1","name2":"value2","name3":"value3"...}  

  6.        if(curRowData['name1'] == ""){  

  7.            //dosomething  

  8.        }  

  9.        //更改:更改name1的值  

  10.        $.extend(curRowData, {"name1":"newValue1"})  

  11.        $("#jqGrid_id").jqGrid('setRowData', rowIds[i], curRowData);  

  12.    }  

  13. }  

6、获取grid参数.

name表示grid的options:http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid('getGridParam','name');  

7、设置grid参数,与上面的方法对应

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid('setGridParam', 'name');  

如下常见需要获取的参数:

Js代码   收藏代码
  1. #获取总记录数  

  2. $("#jqGrid_id").jqGrid('getGridParam','records');  

  3. #获取请求参数  

  4. $("#jqGrid_id").jqGrid('getGridParam','postData');  

  5. #获取选中的row,返回string  

  6. $("#jqGrid_id").jqGrid("getGridParam","selrow");  

  7. #获取选中的多个row,返回Array  

  8. $("#jqGrid_id").jqGrid("getGridParam","selarrrow");  

例子:对当前默认请求添加新的请求参数

Js代码   收藏代码
  1. var postData = $("#jqGrid_id").jqGrid('getGridParam','postData'); $.extend(postData , {"name1":"newValue1"}) $("#jqGrid_id").jqGrid("setGridParam", {datatype: "json" }).trigger("reloadGrid", [{page:1}]);  

同时,在实际的使用场景中,我们可能是需要选择通过选择表单的值再进行查询:

Js代码   收藏代码
  1. $("#queryBtn").bind("click", function() {  

  2.    var sdata = {  

  3.        "ware.warename" : $("#warenameId").val(),  

  4.        "ware.number" : $("#numberId").val(),  

  5.        "ware.valid" : $("#validId").val()  

  6.    };  

  7.    var postData = $("#jqGridId").jqGrid("getGridParam", "postData");  

  8.    $.extend(postData, sdata);  

  9.    $("#jqGridId").jqGrid("setGridParam", {search: true}).trigger("reloadGrid", [{page:1}]);  

  10. });  

8、删除

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid("delRowData", rowid); //前台删除  

 在使用上述API进行批量删除时,是根据rowid去删除指定的行,但是在删除过程中rowid会导致变化,如果采用下面的方式删除会导致某些行不能被删除:

Js代码   收藏代码
  1. var gr = $("#jqGrid_id").jqGrid("getGridParam","selarrrow"); //删除选中的出库单  

  2. for ( var i = 0, j = gr.length; i < j; i++) {  

  3.    $("#jwGrid_id").jqGrid('delRowData', gr[i]);  

  4. }  

在网上找到一个解决方案是:

Js代码   收藏代码
  1. var gr = $("#jqGrid_id").jqGrid("getGridParam","selarrrow"); //删除选中的出库单  

  2. for ( var i = 0, j = gr.length; i < j; i++) {  

  3.    $("#jwGrid_id").jqGrid('delRowData', gr[0]);  

  4. }  

上述API是前端删除,对于前后台交互的删除的API:

Js代码   收藏代码
  1. $("#jqGrid_id").jqGrid("delGridRow", rowid);  

下面是一个删除的例子:

Js代码   收藏代码
  1. $("#removeBtn").bind("click", function(){  

  2.    var gr = $("#jqGridId").jqGrid('getGridParam','selrow');  

  3.    if(gr){  

  4.        var rowData = $("#jqGridId").jqGrid("getRowData", gr);  

  5.        $("#jqGridId").jqGrid('delGridRow', gr ,{  

  6.            top: 100,  

  7.            left: 400,  

  8.            reloadAfterSubmit:false,  

  9.            modal: true,                            //模态窗口  

  10.            url: s2web.appURL + "jq/del.action",    //覆盖editUrl  

  11.            jqModal: true,  

  12.            beforeSubmit: function(postData, formid){// id=value1,value2,...  

  13.                var editData = {  

  14.                        "ware.id": rowData.id  

  15.                };  

  16.                postData = $.extend(postData, editData);    

  17.                console.log(postData);  

  18.                return[true,"success"];  

  19.            },  

  20.            afterSubmit: function(xhr, postData){   //返回[success, message, new_id]  

  21.                console.log(postData);  

  22.                if(xhr.responseText == "\"1\""){  

  23.                    //alert("保存成功");  

  24.                    return [true,"保存成功",postData.id];  //message is ignored if success is true  

  25.                }  

  26.                return [false,"保存失败",postData.id];  

  27.            }  

  28.        });  

  29.    }else{  

  30.        alert("请选择要删除的数据");  

  31.    }  

  32. });  

5、事件(Event)

作为jqGrid的各种事件属性,用来监听相应的事件,如选择行、完成加载、多选等时候触发。API参见http://www.trirand.com/jqgridwiki/doku.php?id=wiki:events,这里还介绍了关联事件的执行顺序:

写道
Below is the execution order of the events when a ajax request is made
1、beforeRequest
2、loadBeforeSend
3、serializeGridData
4、loadError (if a error from the request occur - the event from steps 5 till 7 do not execute. If there is no error the event 4. does not execute and we continue to with the step 5.)
5、beforeProcessing
6、gridComplete
7、loadComplete

下面的例子是在开发中比较关注的onSelectRow和gridComplete事件,完成如下功能:在选中行时获取当前行的数据并以某种方式查看数据,在列表加载完时计算列表中各个行的某列的合计值等:

Js代码   收藏代码
  1.   //设置multiselect checkbox's value,设置总的称重和件数  

  2.   gridComplete: function(){  

  3.    var rowIds = $("#wmsjQContentTableId").jqGrid('getDataIDs');  

  4.    var totalWeight = 0,totalNumber = 0;  

  5.          for(var i = 0, j = rowIds.length; i < j; i++) {  

  6.             var curRowData = $("#wmsjQContentTableId").jqGrid('getRowData', rowIds[i]);  

  7.             var curChk = $("#"+rowIds[i]+"").find(":checkbox");  

  8.             curChk.attr('name', 'wmsCheckboxname');  

  9.             curChk.attr('value', curRowData['outStockCode']);  

  10.             if(curRowData['weight'] != ""){  

  11.               totalWeight += parseFloat(curRowData['weight']);  

  12.             }  

  13.             if(curRowData['number'] != ""){  

  14.               totalNumber += parseFloat(curRowData['number']);  

  15.             }  

  16.          }  

  17.        $("#totalWeighId").val(totalWeight);  

  18.        $("#totalPackNumId").val(totalNumber);  

  19. },  

  20.  

  21. //行选中时更新称重、件数、出库单  

  22. onSelectRow: function(ids){  

  23.    var rowData = $("#wmsjQContentTableId").jqGrid("getRowData", ids);  

  24.    $("#curWeighId").val(rowData['weight']);  

  25.    $("#packNumId").val(rowData['number']);  

  26.    $("#curWmsOutStockCodeId").val(rowData['outStockCode']);  

  27. }  

考虑如下一种场景,在列表的最后一列一般会有要求操作栏,提供删除、修改等操作,那么同样也可以通过gridComplete事件来实现:

Java代码   收藏代码
  1. colNames:['商品编号', '商品名称', '单价','采购日期','库存','状态','操作'],//表头  

  2. 在colModel中有一列空值占位,注意index不要和json中重复  

  3. {name:'act',        index:'act',        width:150}    

在gridComplete事件中:

Js代码   收藏代码
  1.   gridComplete: function(){  

  2.    var ids = $("#jqGridId").jqGrid('getDataIDs');  

  3.    for(var i=0, j=ids.length; i < j; i++){  

  4.        var cl = ids[i];  

  5.        be = "+cl+"');\"  />  ";  

  6.        //se = "  ";  

  7.        se = "+cl+"');\"  />  ";  

  8.        ce = "+cl+"');\" />";  

  9.        $("#jqGridId").jqGrid('setRowData',ids[i], {act: be + se + ce});  

  10.    }    

  11. },  

6、其他

冻结行、列

jqGrid有提供对column、header、column with group header的冻结,

需要设置两处:

Js代码   收藏代码
  1. colModel中的frozen:true  

  2. $("#grid").jqGrid('setFrozenColumns');  

但是jqGrid对冻结的支持并不是那么强大,只能支持依次从左到右冻结,如果中间设置有一个cell没有设置,那么该row以后的cell即使设置了也不起作用

在官方的DOC中列出了使用限制:

写道
The following limitations tell you when frozen columns can not be set-up
When TreeGrid is enabled
When SubGrid is enabled
When cellEdit is enabled
When inline edit is used - the frozen columns can not be edit.
When sortable columns are enabled - grid parameter sortable is set to true or is function
When scroll is set to true or 1
When Data grouping is enabled

动态改变设置:当然这里id、name都是依次从左到右的元素

$("#changeBtn").bind("click", function() {

Js代码   收藏代码
  1. $("#jqGridId").jqGrid('destroyFrozenColumns')  

  2. .jqGrid('setColProp','id', {frozen:true})  

  3. .jqGrid('setColProp','name', {frozen:true})  

  4. .jqGrid('setFrozenColumns')  

  5. .trigger('reloadGrid', [{current:true}]);  

  6. );  

7、参考以下文章

doc:
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:jqgriddocs
options:
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options
colmodel_options:
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:colmodel_options
方法
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:methods
事件
http://www.trirand.com/jqgridwiki/doku.php?id=wiki:events

其他

http://blog.csdn.net/gengv/article/category/648499

http://www.trirand.com/jqgridwiki/doku.php

http://trirand.com/blog/jqgrid/jqgrid.html



本文链接: jQuery表格插件jqGrid(jquery.jqGrid.js)http://www.656463.com/article/488

如非特别注明,本站内容均为 领悟书生原创,转载请务必注明作者和原始出处。
本文地址: http://www.656463.com/article/Qbay6j.htm

你可能感兴趣的:(jquery,jqGrid)