jqgrid json数据格式

ligerUI的表格的介绍文档内容过于简洁，不易学习，且貌似近年来没有多少更新和维护；datatables样式虽然美观大气，但是她的学习文档依旧让初学者很头疼，文档中各参数关系错综复杂，要弄明白一个参数的含义，可能需要不停的跳转页面找解释。easyUI的datagrid的介绍文档多是例子，没有多少api、参数的讲解。个人觉得不论是什么插件，即使其功能再高大上，如果她的api文档写的很烂，用起来很吃力，除非有足够的经理，否则迟早会被放弃使用。尽量让事情简单点，不要搞复杂。在尝试了以上各表格插件后，发现jqgrid学起来最轻松，api文档也是最易懂的。

接下来进入本文的主题，即jqgrid json 数据格式。首先，为大家展示一个非常简单基本Demo。使用jqGrid绘制一张表格。

HTML

<table id="list2"></table>
<div id="pager2"></div>

JS

jQuery("#list2").jqGrid({
        url:'server.php?q=2',
        datatype: "json",
        colNames:['Inv No','Date', 'Client', 'Amount','Tax','Total','Notes'],
        colModel:[
             {name:'id',index:'id', width:55},
             {name:'invdate',index:'invdate', width:90},
             {name:'name',index:'name asc, invdate', width:100},
             {name:'amount',index:'amount', width:80, align:"right"},
             {name:'tax',index:'tax', width:80, align:"right"},        
             {name:'total',index:'total', width:80,align:"right"},        
             {name:'note',index:'note', width:150, sortable:false}        
        ],
        rowNum:10,
        rowList:[10,20,30],
        pager: '#pager2',
        sortname: 'id',
        viewrecords: true,
        sortorder: "desc",
        caption:"JSON Example"
 });
 jQuery("#list2").jqGrid('navGrid','#pager2',{edit:false,add:false,del:false});

各参数含义如下：

• url ：这个参数指定了jqGrid从服务器获取数据的请求。
• datatype ：这个参数指定了jqGrid调用的数据的格式，常用格式有json，xml，local。
• colName ：这个参数指定了jqGrid每列的title，按顺序依次排列，并且可以看出实际上它就是一个字符串数组。
• colModel ：这个参数指定了jqGrid各列的具体格式，"name"指定对应数据中属性名，“index”用于列排序，“width”显然是指定列宽，“align”对齐方式，“sortable”指定是否支持排序。其实上面每一个设置基本见名知意，大家可以大胆使用。（注意：colName与colModel 需要一一对应）
• rowNum ：这个参数指定了jqGrid显示行数，默认值20。
• rowList ：这个参数指定了jqGrid可以接受的rowNum值，如[10,20,30]。实际上它也仅仅是一个数组。
• pager ：这个参数指定了jqGrid页脚显示位置。
• sortname ：这个参数指定了jqGrid默认的排序列，可以是列名也可以是数字。
• viewrecords ：这个参数设置了是否在Pager Bar显示所有记录的总数。
• sortorder ：这个参数指定了jqGrid默认排序列的默认排序方式。
• caption ：这个参数制订了jqGrid的标题，如果设置了，则将显示在Grid的Header层。

上面表格中使用的json数据：

{
  "page": "1",
  "total": 2,
  "records": "13",
  "rows": [
    {
      "id": "13",
      "cell": [
        "13",
        "2007-10-06",
        "Client 3",
        "1000.00",
        "0.00",
        "1000.00",
        null
      ]
    },
    {
      "id": "12",
      "cell": [
        "12",
        "2007-10-06",
        "Client 2",
        "700.00",
        "140.00",
        "840.00",
        null
      ]
    },
    {
      "id": "11",
      "cell": [
        "11",
        "2007-10-06",
        "Client 1",
        "600.00",
        "120.00",
        "720.00",
        null
      ]
    },
    {
      "id": "10",
      "cell": [
        "10",
        "2007-10-06",
        "Client 2",
        "100.00",
        "20.00",
        "120.00",
        null
      ]
    },
    {
      "id": "9",
      "cell": [
        "9",
        "2007-10-06",
        "Client 1",
        "200.00",
        "40.00",
        "240.00",
        null
      ]
    },
    {
      "id": "8",
      "cell": [
        "8",
        "2007-10-06",
        "Client 3",
        "200.00",
        "0.00",
        "200.00",
        null
      ]
    },
    {
      "id": "7",
      "cell": [
        "7",
        "2007-10-05",
        "Client 2",
        "120.00",
        "12.00",
        "134.00",
        null
      ]
    },
    {
      "id": "6",
      "cell": [
        "6",
        "2007-10-05",
        "Client 1",
        "50.00",
        "10.00",
        "60.00",
        ""
      ]
    },
    {
      "id": "5",
      "cell": [
        "5",
        "2007-10-05",
        "Client 3",
        "100.00",
        "0.00",
        "100.00",
        "no tax at all"
      ]
    },
    {
      "id": "4",
      "cell": [
        "4",
        "2007-10-04",
        "Client 3",
        "150.00",
        "0.00",
        "150.00",
        "no tax"
      ]
    }
  ],
  "userdata": {
    "amount": 3220,
    "tax": 342,
    "total": 3564,
    "name": "Totals:"
  }
}

看到jqGrid实际调用的json格式以后，很多读者朋友会产生疑问。是否只有符合上面格式的json数据才能被jqGrid解析？答案是：否定的

这里就不得不介绍一下jqGrid的一个重要的选项jsonReader，jsonReader用于设置如何解析从Server端发回来的json数据。上面表格之所以能够成功解析出来得益于，jsonReader的默认设置。

jsonReader默认设置：

jsonReader : {
      root: "rows",    // json中代表实际模型数据的入口
      page: "page",    // json中代表当前页码的数据
      total: "total",    // json中代表页码总数的数据
      records: "records", // json中代表数据行总数的数据
      repeatitems: true, // 如果设为false，则jqGrid在解析json时，会根据name来搜索对应的数据元素（即可以json中元素可以不按顺序）；而所使用的name是来自于colModel中的name设定。
      cell: "cell",      //当前行的所有单元格
      id: "id",          //行id
      userdata: "userdata",  //从服务器端返回一些参数但并不想直接把他们显示到表格中，而是想在别的地方显示
      subgrid: {
      	root:"rows", 
      	repeatitems: true, 
      	cell:"cell"
     }
 }

如果Server端返回的json数据不太符合默认设置（比如内容结构不同）那么就有必要修改这一设置。

通常jsonReader和repeatitems是配合使用的，如果repeatitems为false，json 中数据可以乱序，并且允许数据空缺。jqGrid会根据colModel中name属性和json数据对应，根据属性名称进行解析。

repeatitems为true时：

 ...
     jsonReader : {
         root:"rows",
         page: "page",
         total: "total",
         records: "records"
     },
     ...

json结构：

{ 
      "page": "xxx", 
      "total": "yyy",
      "records": "zzz",
      "rows" : [
                   {"id" :"1", "cell" :["cell11", "cell12", "cell13"]},    // cell中不需要各列的name，但是需要与colModel一一对应
                   {"id" :"2", "cell" :["cell21", "cell22", "cell23"]},
                   ...
      ]
 }

repeatitems为false时：

...
    repeatitems: false,
    jsonReader : {
      root:"rows",
      page: "page",
      total: "total",
      records: "records"
   },
   ...

json结构：

{ 
      "page" : "xxx", 
      "total" : "yyy",
      "records" : "zzz",
      "rows" : [
           {"invid" : "1","invdate":"cell11", "amount" :"cell12", "tax" :"cell13", "total" :"1234", "note" :"somenote"}, // 数据中需要各列的name，但是可以不按列的顺序
           {"invid" : "2","invdate":"cell21", "amount" :"cell22", "tax" :"cell23", "total" :"2345", "note" :"some note"},
           ...
      ]
 }