jqGrid中文说明文档——事件和方法

jqGrid提供了大量的事件和方法可以调用，方便开发者通过事件响应处理以及动态的调用方法来对jqGrid表格的操作，满足不同情况下的开发需求。了解jqGrid选项、事件及方法后，你可以尽情发挥，让jqGrid为你做更多的事情。



jqGrid事件(Events)

通过事件响应来设置jqGrid的表格属性，其使用语法为：

var lastSel;
jQuery("#gridid").jqGrid({
...
   onSelectRow: function(id){ 
      if(id && id!==lastSel){ 
         jQuery('#gridid').restoreRow(lastSel); 
         lastSel=id; 
      } 
      jQuery('#gridid').editRow(id, true); 
   },
...
});

上述代码表明，当选中表格中的行时将要发生的事情。以下是jqGrid提供的事件列表。




事件
参数
描述


afterInsertRow
rowid 

rowdata 

rowelem
此事件发生在每次插入行后

rowid 为插入的行ID

rowdata 是被插入行的数据数组。格式为name:value对，name在colModel定义

rowelem 是应答元素。xml为xml行，json为所有行数据。

注意：若gridview 为true，此事件不会发生


beforeRequest
none

此事件发生在任何数据请求前，但当datatype为function时不发生。


beforeSelectRow
rowid, e
此事件发生在用户点击行，选中该行前。

rowid 为行的ID，e为事件对象

该事件将返回布尔值true（行被选中）或false（行未被选中）。


gridComplete
none
此事件发生在表格所有数据装入和进程完成后。与datatype参数及排序分页等无关。


loadBeforeSend
xhr,

settings
此事件发生在XMLHttpRequest被发送前，用于修改对象属性（如headers）。
xhr 为XMLHttpRequest对象。


loadComplete
data
此事件发生在每个服务器请求后。xhr 为XMLHttpRequest对象。


loadError
xhr,

status,

error
此事件在请求失败时发生。事件有3个参数：

xhr 为XMLHttpRequest对象；

Satus 为错误类型描述；error 为错误对象。



onCellSelect
rowid,

iCol, 

cellcontent,

e
此事件在点击表格特定单元格时发生。

rowid 为行ID；iCol 为列索引；

cellcontent 为单元格中内容；

e 点击事件对象。



ondblClickRow
rowid, 

iRow, 

iCol, 

e
此事件发生在行双击后发生。

rowid为行ID；iRow 为行索引（勿与rowid混淆）；

iCol为列索引；

e 为事件对象。


onHeaderClick
gridstate
此事件发生在点击显示或隐藏表格后发生（hidegrid为true）
gridstate为表格状态，有visible和hidden两个值


onPaging
pgButton
此事件发生在点击page button后，填充数据前，及用户输入一个与当前页页码不同的新页码并回车时。


onRightClickRow
rowid, 

iRow, 

iCol, 

e
此事件发生在右击行后。（此事件在Opera浏览器中无效）

rowid为行ID；iRow为行索引（勿与rowid混淆）

iCol为列索引；

e为事件对象


onSelectAll
aRowids,

status
此事件发生在点击标题的复选框时发生（multiselect为true）

aRowids 选定行ID的数组（哪些行的复选框与头复选框相同）

status 头复选框的选定的布尔值，true为选中，false为


onSelectRow
rowid,

status
此事件发生在行点击后

rowid 为行ID；

status  为选择状态。当multiselect为true时使用，当行被选中时返回true；为选中时返回false。


onSortCol
index,

iCol,

sortorder
此事件发生在列排序被点击之后，数据排序前

index 为colModel 中定义的索引名iCol 为列的索引号

sortorder 为新的排序方式，asc或desc


resizeStart
event, index
此事件发生在列被重新定义宽度时。
event 为事件对象；index 为在colModel 中定义的列索引。


resizeStop
newwidth, index
此事件发生在列被重新定义宽度后。

newwidth 为新的列宽度；index 为在colModel 中定义的列索引。


serializeGridData
postData
通过此事件可以序列化传递给ajax请求的的数据。此事件将返回一个以序列化的数据。若有自定义的数据（如JSON字符串、XML字符串）要发给服务器时，可使用该事件。



关于单元格编辑、子表的事件情参阅Cell Editing, subGrid


jqGrid方法(Methods)

调用jqGrid的方法很简单，使用以下代码：

jQuery("#grid_id").jqGridMethod( parameter1,...parameterN );

这里：grid_id是表格的id；

jqGridMethod为jqGrid方法；

parameter1,…parameterN为参数列表

若方法未定义返回值，则返回到jqGrid对象，一组方法可以链接起来，例如

jQuery("#grid_id").setGridParam({...}).hideCol("somecol").trigger("reloadGrid");

或使用新的接口

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

这里： grid_id是表格的id；

Method是方法名；

parameter1,…parameterN是参数列表。

以下是jqGrid提供的一系列方法：




方法
参数
返回值
描述


addJSONData
data
none
用传递的data（数组）填充网格。用法：假如我们从web服务器获得的数据（jsonresponse），则

var mygrid = jQuery(”#”+grid_id)[0];

var myjsongrid = eval(”(”+jsonresponse.responseText+”)”);

mygrid.addJSONData(myjsongrid);

myjsongrid = null;

jsonresponse =null;

将填充网格。当然，myjsongrid中的数据在传递到addJSONData之前可以被操作。


addRowData
rowid,

data, 

position, 

srcrowid
true on success, 

false otherwise
插入一新行，rowid 为新行的ID，data（数组）为新行数据，position为新行插入的位置（first为表头，last为表尾，srcrowid指定偏移位置）。Data数组的格式为：{name1:value1,name2: value2…} ，name为colModel指定的名称。



addXmlData
data
none

用传入的data填充网格。用法：假如我们从web服务器获得数据

(xmlresponse)，则
var mygrid = jQuery(”#”+grid_id)[0];


mygrid.addXmlData(xmlresponse.responseXML);

将填充网格。当然，xmlresponse中的数据在传递到addXmlData之前可以被操作。



clearGridData
clearfooter
jqGrid object
清除网格中当前装入的数据，如果clearfooter 参数为true，则清除网格最后一行数据。


delRowData
rowid
true on success, 

false otherwise
删除id = rowid的行。但不会删除服务器上的数据。


footerData
action,

data, 

format
jqGrid object
此方法获得或设置网格底部数据。

action – 可设置为get（缺省）或set。 Get从底部返回name:value对象（name为colModel中的名称）。此时其他两个参数无效。

Set将data数组（对象）设置到底部。Data为colName中的名称和值对。

format – 缺省为true，表示设置时使用formatter (如果colModel中已定义)。false表示不使用formatter


getCell
rowid, 

iCol
cell content
返回id = rowid行，column = iCol列的内容。 iCol可以是列的索引或colName中定义的名称。在编辑行或列时不能使用该方法，此时返回的不是当前值，而是原始值。


getCol
colname, returntype, mathoperation
array[] or value
返回列值数组。

colname 可以是列的索引值或colModel中的名称。returntype 确定返回数组的类型，为false(缺省)时，数组只包含值。为true时为对象数组，格式为{id:rowid, value:cellvalue}，id为行的id， cellvalue为单元格的值。如 [{id:1,value:1},{id:2,value:2}…]


mathoperation为可选参数，可以是sum、avg和count。若此参数进行了有效设置，则返回计算后的值，若无效，则返回空数组。



getDataIDs
none
array[]
返回当前网格显示数据的ID数组。无数据时返回空数组。


getGridParam
name
mixed value
返回请求的参数的值。name 是options 数组中的名称，若为设置则options被返回。 详见jqGrid中文说明文档——选项设置.


getInd
rowid,

rowcontent
mixed
当rowcontent 设置为false（缺省）时，返回id= rowid行的索引值。若rowcontent设置为true，则返回整行。若为找到rowid则返回false。


getLocalRow
rowid
row object
Return the row data from the local array stored in data parameter when the datatype is local


getRowData
rowid or none
array{}
返回id = rowid行的数据数组。格式为name:value对，name为colModel中的名称，value为该行的值。未找到返回空数组。在行或列编辑时此方法不可用，此时返回的不是当前值，而是原始值。

若rowid为设置，则返回网格中所有数据数组。



hideCol
colname

or

[colnames]
jqGrid object
根据colname或colnames数组给定的列名隐藏相应的列，列名必须是colModel中定义的名称。表格的宽度不会改变。


remapColumns
permutation, updateCells, keepHeader
none
调整列的显示顺序。permutation指定调整后的顺序，如 [1,0,2] 表示第一列在第二位显示。若updateCells 设置为true，列数据将重新排序。若keepHeader 设置为true，header单元格将重新排序。


resetSelection
none
jqGrid object
选择（反选）行。多选择模式下同样可用。


setCaption
caption
jqGrid object
设置新的表头文字。若表头为隐藏，将显示。


setCell
rowid,

colname, 

data, 

class, 

properties, 

forceup
jqGrid object

修改单元格的值、类或样式。其中：

rowid为行ID；colname为列名（可以是从0开始的列的索引值）；

data 设置的内容，若为空，class若为字符串，将使用addClass为列加入一个类，若为数组，将直接加入CSS中；properties 设置单元格属性。


setGridParam
object
jqGrid object
设置一个特定的参数。

有些参数需trigger(“reloadGrid”)才能生效。注意这个方法可以覆盖事件。名称（name:value对）为选项数组中的名称。 选项信息参见jqGrid中文说明文档——选项设置.


setGridHeight
new_height
jqGrid object
动态设置网格高度。只能对单元格的高度进行设置而不是网格。new_height 可以是像素、百分比或auto。


setGridWidth
new_width,

shrink
jqGrid object
动态设置网格宽度。new_width 为新宽度的像素值；

shrink（true或false）作用同shrinkToFit。若不设置，则使用shrinkToFit设置。


setLabel
colname, 

data, 

class, 

properties
jqGrid object

设置指定列标题文字、属性和类：

colname 为列名，可以是从0开始的列索引；

data 为标题文字，为空则不修改；

class 若为字符串，则为类名，若为数组，则直接写入CSS；

properties 为标题文字的属性。



setRowData
rowid,

data, 

cssprop
true on success, 

false otherwise
更新rowid指定行的数据（使用数组）。

Data数组的格式为: {name1:value1,name2: value2…} 。name为colModel中描述的名称，value为新值。cssprop若为字符串，将使用addClass为行添加类；若为数组对象，则直接加入CSS中。将data设置为false的情况下，可设置属性和类名


setSelection
rowid,

onselectrow
jqGrid object
选择或反选id = rowid指定的行。若onselectrow设置为true (缺省) 则触发onSelectRow事件，否则不触发。


showCol
colname
jqGrid object
显示colname 指定的列。若colname为字符串，只显示指定的列，若colname为数组 [“name1”,”name2”] 则显示name1和name2列， name必须是colModel中的名称。宽度不变。


trigger(“reloadGrid”)
none
none
按当前设置重新加载网格。若datatype为xml或json，将从服务器重新请求数据。此方法适用于一个已建立的网格。注意不会改变表头，也就是说改变colModel将没有作用。你可用gridUnload，使用新colModel来重新加载。


updateColumns
none
none
在拖拽表格时，同步网格宽度。用法：

var mygrid=jQuery(”#grid_id”)[0];

mygrid.updateColumns();