【JqGrid】jqGrid API之用法

比眉伴天荒 2022-07-14 04:49 209阅读 0赞

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

**1、引入到项目中来**

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

Js代码   ![收藏代码][icon_star.png]

1.  <link rel="stylesheet" type="text/css" href="$request.contextPath/script/jqGrid/css/ui.jqgrid.css" />   
2.  <script type="text/javascript" src="$request.contextPath/script/jqGrid/js/jquery.jqGrid.min.js"></script>   
3.  <script type="text/javascript" src="$request.contextPath/script/jqGrid/js/i18n/grid.locale-cn.js"></script>

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

Js代码   ![收藏代码][icon_star.png]

1.  <link rel="stylesheet" type="text/css" href="$request.contextPath/script/jqGrid/css/jquery-ui-1.8.22.custom.css" media="all"/>   
2.  <script type="text/javascript" src="$request.contextPath/script/ui/jquery-ui-1.8.22.custom.min.js"></script>   
3.  <script type="text/javascript" src="$request.contextPath/script/ui/jquery.ui.datepicker-zh-CN.js"></script>

**2、在页面中使用**

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

Js代码   ![收藏代码][icon_star.png]

1.  <table id="jqGridId"></table> //这个是必须的   
2.  <div id="pager"></div> //这个是显示分页bar的信息，根据需要

然后在js中

Js代码   ![收藏代码][icon_star.png]

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][http_www.trirand.com_jqgridwiki_doku.php_id_wiki_options]

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

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  **public** **class** PageModule<T> **extends** JqGridQueryBase \{  
2.    
3.      **private** **static** **final** **long** serialVersionUID = -663611670315885315L;  
4.      /\*\* 查询返回结果数据 \*/  
5.      **private** List<T>           list             = **new** ArrayList<T>();

**colModel：** colModel对json数组中对象如何解析填充到表格的cell的设定，包括基本的name、index、width、formater等，具体见[http://www.trirand.com/jqgridwiki/doku.php?id=wiki:colmodel\_options][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][http_blog.csdn.net_jpr1990_article_details_6891115]

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

Js代码   ![收藏代码][icon_star.png]

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

支持下拉select的设定：

Js代码   ![收藏代码][icon_star.png]

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

显示链接：

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  jQuery("\#grid\_id").jqGridMethod( parameter1,...parameterN );   
2.  jQuery("\#grid\_id").jqGrid('method', parameter1,...parameterN );

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

Js代码   ![收藏代码][icon_star.png]

1.  jQuery("\#grid\_id").jqGrid('setGridParam',\{...\}).jqGrid('hideCol',"somecol").trigger("reloadGrid");

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

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid("addRowData", "1" ,\{ 'name':'zhangsan', 'age': 20\}, "first" );

2、清空grid

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid("clearGridData");

3、返回当前grid序号

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid('getDataIDs');

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

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid('getRowData', rowIds\[i\]);

5、设置某row值

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid('setRowData', rowIds\[i\], \{\});

一个例子：需要对grid中的数据进行循环遍历获取、设置、更改

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid('getGridParam','name');

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

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid('setGridParam', 'name');

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

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  **var** postData = $("\#jqGrid\_id").jqGrid('getGridParam','postData'); $.extend(postData , \{ "name1":"newValue1"\}) $("\#jqGrid\_id").jqGrid("setGridParam", \{datatype: "json" \}).trigger("reloadGrid", \[\{page:1\}\]);

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

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid("delRowData", rowid); //前台删除

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

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

上述API是前端删除，对于前后台交互的删除的API：

Js代码   ![收藏代码][icon_star.png]

1.  $("\#jqGrid\_id").jqGrid("delGridRow", rowid);

下面是一个删除的例子：

Js代码   ![收藏代码][icon_star.png]

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][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代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

1.  colNames:\['商品编号', '商品名称', '单价','采购日期','库存','状态','操作'\],//表头  
2.  在colModel中有一列空值占位，注意index不要和json中重复  
3.  \{name:'act',        index:'act',        width:150\}

在gridComplete事件中：

Js代码   ![收藏代码][icon_star.png]

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 = "<input style='height:22px;width:40px;' type='button' value='编辑' οnclick=\\"$('\#jqGridId').editRow('"\+cl+"');\\"  />&nbsp;&nbsp;";   
6.          //se = "<input style='height:22px;width:40px;' type='button' value='保存' οnclick=\\"$('\#jqGridId').saveRow('"+cl+"');\\"  />&nbsp;&nbsp;";  
7.          se = "<input style='height:22px;width:40px;' type='button' value='保存' οnclick=\\"customSaveRow('"\+cl+"');\\"  />&nbsp;&nbsp;";   
8.          ce = "<input style='height:22px;width:40px;' type='button' value='取消' οnclick=\\"$('\#jqGridId').restoreRow('"\+cl+"');\\" />";   
9.          $("\#jqGridId").jqGrid('setRowData',ids\[i\], \{act: be + se + ce\});  
10.     \}     
11. \},

**6、其他**

**冻结行、列**

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

需要设置两处：

Js代码   ![收藏代码][icon_star.png]

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代码   ![收藏代码][icon_star.png]

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

[http_www.trirand.com_blog]: http://www.trirand.com/blog/
[http_www.trirand.com_jqgridwiki_doku.php]: http://www.trirand.com/jqgridwiki/doku.php
[icon_star.png]: /images/20220714/77f108bdb4334f72b24b4680ef00842c.png
[http_jqueryui.com_themeroller]: http://jqueryui.com/themeroller/
[http_www.trirand.com_jqgridwiki_doku.php_id_wiki_options]: http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options
[http_www.trirand.com_jqgridwiki_doku.php_id_wiki_colmodel_options]: http://www.trirand.com/jqgridwiki/doku.php?id=wiki:colmodel_options
[http_blog.csdn.net_jpr1990_article_details_6891115]: http://blog.csdn.net/jpr1990/article/details/6891115
[http_www.trirand.com_jqgridwiki_doku.php_id_wiki_events]: http://www.trirand.com/jqgridwiki/doku.php?id=wiki:events