jqGrid方法

  本章介绍jqGrid基础方法。一些方法需要加载额外的模块。为了兼容jQuery UI类库,jqGrid3.6+使用新API来调用方法。相关信息: jqGrid事件

grid相关方法

调用方式

jQuery("#grid_id").jqGridMethod( parameter1,...parameterN );
示例说明
  • grid_id :已经调用jqGrid方法构造过的DOM对象id
  • jqGridMethod :属于jqGrid的方法名称
  • parameter1,…parameterN :参数列表

  如果一个方法未被设计为返回一个需要的值,那么将返回 jqGrid对象,这样就可以链式调用jqGrid相关的方法,例如

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

新API

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

示例说明

  • grid_id:已经调用jqGrid方法构造过的DOM对象id
  • jqGrid :jqGrid的实例
  • method :属于jqGridis的方法。注意方法名称需要用单引号或者双引号括起(传递字符串)
  • parameter1,…parameterN :参数列表

给出的示例新API调用如下

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

旧的和新的API都可以使用,所以之前的用户不需要更新代码。创建新API的原因是为了解决和另外的插件名称空间冲突(就是方法名称冲突,如果其他插件也扩展了jQuery对象的方法,名称一样,这样就会起冲突。)。要使用新API,看下面的配置。

配置jqGrid只使用新APIConfiguring jqGrid to use only the new API

在安装过程中配置这些步骤

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>My First Grid</title>
 
<link rel="stylesheet" type="text/css" media="screen" href="css/ui-lightness/jquery-ui-1.7.1.custom.css" />
<link rel="stylesheet" type="text/css" media="screen" href="css/ui.jqgrid.css" />
 
<script src="js/jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="js/i18n/grid.locale-en.js" type="text/javascript"></script>
<script type="text/javascript">
	jQuery.jgrid.no_legacy_api = true;//////////////
</script>
<script src="js/jquery.jqGrid.min.js" type="text/javascript"></script>
 
</head>
<body>
...
</body>
</html>

注意这句

jQuery.jgrid.no_legacy_api = true;

这句代码需要放置在js语言文件之后,jqGrid核心js代码之前。

 

方法名称标记为绿色的 需要特殊的调用程序,对照示例查看个别方法描述。
方法名称 参数 返回值 描述
addJSONData data none 将data参数(键值对)的数据添加到表格中。示例如下,数据从执行的webservice返回
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
向jqGrid中添加新数据行
  • rowid:这个值将作为行的id
  • data:和colModel中定义的name一样,json键值对对象,如{name1:value1,name2: value2…},name来自colModel中配置的name值。
  • position:指定数据添加的位置,可以为first, last, before 或者after
    1)"first" 在grid顶部添加一行数据【默认值】
    2) "last" 再grid最后添加一行数据
    3)"before" 和 "after" 依据srcrowid.配置的值
  • srcrowid:使用"before" 或者 "after"插入新数据到grid中需要参考的某行id值

这个方法可以一次插入多行数据,此时data参数格式如下
[{name1:value1,name2: value2…}, {name1:value1,name2: value2…} ]
这是rowid参数指定数据中的键名字作为数据行的id,此时rowid的配置不一定从colModel中配置的name值中选出来。

addXmlData data none 将xml数据添加到表格中,示例
var mygrid = jQuery("#"+grid_id)[0];//官网这句应该有问题,应该为jQuery("#"+grid_id),[0]操作后就是DOM对象了
mygrid.addXmlData(xmlresponse.responseXML); 
xmlresponse 可以在传递到addXmlData方法前进行其他的处理。
bindKeys {
onEnter: null,
onSpace: null,
onLeftKey: null, onRightKey: null,
scrollingRows : true
}
jqGrid object 绑定键盘的快捷键,可以通过上下方向键选择行,使用按键滚动表格中的数据。当行被选择后,按下Enter,Space(空格键),左右方向键,还可以调用附加的事件。这些事件的参数为选中的数据行id
clearGridData clearfooter jqGrid object 删除表当前加载的数据。clearfooter参数设置为true,附加在页脚的数据也会被清空。
delRowData rowid true on success,
false otherwise
删除grid中指定id的数据行,此操作不会从服务器删除对应的数据。
editRow rowid,
keys
none? 通过指定的数据行id编辑此行。keys 为布尔值,是否启用Enter键保存数据,Esc间取消编辑。
footerData action,
data,
format
jqGrid object 设置或者获取页脚数据。参考:jqGrid选项配置
  • action :可以为 'get' 或者 'set'。默认为get,返回页脚数据的键值对对象,键名称来自colModel中的name值。为get时可以忽略另外2个参数。为set,设置页脚数据。
  • data:设置页脚的数据,键值对对象,键名称来自colModel中的name值
  • format  :默认为true。告诉方法是否使用colModel中的fomatter配置格式化新内容。false将显示原始内容
getCell rowid,
iCol
cell content 返回指定数据行id,此行列号为iCol的单元格内容。iCol可以为列号或者colModel中配置的name值。
在指定的行或者单元格处于编辑状态时不要使用此方法,这将会返回单元格的HTML代码,而不是输入控件的实际内容。
getCol colname, returntype, mathoperation array[] or value 此方法返回列数据值(键值对或者数组)。
  • colname :可以为列号或者colModel中配置的name值
  • returntype :决定返回值类型。默认值false,只包含值。设置为true,为键值对对象,类似{id:rowid, value:cellvalue} ,rowid为数据行id,cellvalue为单元格内容,如[{id:1,value:1},{id:2,value:2}…]
  • mathoperation: 可用值有'sum, 'avg', 'count'.。如果设置了此参数并且为这3个值中的一个,会对所有列值执行指定的操作后再返回操作后的值。如果参数值不正确,将返回空。
getDataIDs none array[] 返回表格中加载的数据行的id数组,数据不可用(如没有数据或者加载数据的ajax未返回前调用了此方法)时返回空数组。
getGridParam name mixed value 返回jqGrid配置的值。name来源于jqGrid的配置名称,如果未指定参数,整个jqGrid的配置都会返回。参考:jqGrid选项配置
getInd rowid,
rowcontent
mixed
  • rowcontent 默认值为false,根据数据行id返回此行所在表格中的行号。
  • rowcontent 设置为 true,将返回数据行对象(TR,至于是否被jQuery包装过没有明说,自己使用时测试下)。
如果找不到数据行,返回false。
getLocalRow rowid row object datatype为local时,返回本地存储的jqGrid配置data数据
getRowData rowid or none array{} 返回指定数据行id的数据(json键值对对象,键名称来自colModel配置的name属性值,值来源于此行对应的列),找不到数据行则返回空对象。
  • 在指定的行或者单元格处于编辑状态时不要使用此方法,这将会返回单元格的HTML代码,而不是输入控件的实际内容
  • 这个方法存在性能问题。Do not use this method in the body of "for" and "when".(调用这个方法,将会计算一次行数据。)
如果不传递rowid参数,将返回grid中的所有数据(json键值对对象数组)
hideCol colname
or
[colnames]
jqGrid object 隐藏colname(来自colModel配置的name值)指定的列。如果传递列名称数组,如['name1','name2'...],将会隐藏数组中指定的列,这些值需要来自colModel配置的name值。这个方法不修改表格的宽度。
remapColumns permutation, updateCells, keepHeader none 依据permutation(数组类型)参数对表格列次序重新排序(排列),这个数组如果没有指定全部列时,指定的列将会从后面插入。
  • permutation :数组的索引下标为新的秩序,值为要重新排序的列原来的位置【这个值从0开始】。
    例如,原来colModel配置了5项,效果如下
    jqGrid方法
    参数值为 [1,0,2],调用这个方法$('#gridid').remapColumns([1,0,2])后,重新排序后如下图所示【原来的第二列,第一列,第三列从后面插入,循序为此数组中先后出现的循序,就是数组的索引下标】
    jqGrid方法
    由上图看到,表头次序变了,但是内容并没有调整过来,这个就需要使用到updateCells参数了,这个参数就是将单元格也一起调整的。默认为false不对内容调整,所以没有对齐。
  • updateCells :默认为false,设置为true将对单元格数据重新排列。修改示例代码,调用$('#gridid').remapColumns([1,0,2],true),单元格也调整过来了
    jqGrid方法
  • keepHeader :默认false。设置为true,表头不会重新排列。
    如果updateCells设置为false,keepHeader设置为true,相当于什么都没调整过。
    $('#gridid').remapColumns([1,0,2],true,true)效果如下
    jqGrid方法
resetSelection none jqGrid object 重置(取消选择)已经选择的列。也可用在多选模式下。
restoreRow rowid none? 还原指定正在编辑的rowid行的数据到原始数据(如果修改保存了多次,则是上一次成功保存的,不是加载时的数据)
saveRow rowid,
callback,
url,
extraparams
none? 保存调用editRow打开编辑的行的数据,rowid要一致,为正在编辑的行的id。
  • callback 为一个函数,成功保存后触发。参数为ajax请求服务器返回的xhr对象。
  • url :保存数据的动态页url地址,指定了这个值将会覆盖jqGrid配置的editurl选项
  • extraparas :提交到服务器的附加参数。
提交到服务器的数据格式为 id=rowid&name=value…,name来自colModel配置的name值。
setCaption caption jqGrid object 设置jqGrid的标题内容。如果原来标题层隐藏的,调用此方法后将会显示。jqGrid布局结构
setCell rowid,
colname,
data,
class,
properties,
forceup
jqGrid object 这个方法可以修改实际单元格的内容和设置单元格style属性。
  • rowid :数据行id
  • colname :列名称(来自colModel的name值,也可以为数字,列下标,从0开始,注意列下标为表格中,不是colModel的。)
  • data :单元格要显示的数据,如果为空字符串,单元格内容保持不变。(可以通过forceup参数来强制更新)
  • class :如果为字符串值,通过addClass方法给单元格增加一个样式;如果为键值对对象,设置css.style属性(键名称为样式名称,值为样式值)。
  • properties :设置单元格的属性(键值对对象)
  • forceup :设置为true,data为空也会更新,就是不管data是什么都执行更新。默认为false
setGridParam object jqGrid object 设置jqGrid的参数(jqGrid已经构造过)。有些参数需要调用trigger("reloadGrid") 后才起作用。这个方法也可以重写事件对象。参数为键值对,详细参阅:jqGrid选项配置
setGridHeight new_height jqGrid object 动态设置表格的高度。(Note that the height is set only to the grid cells and not to the grid,官网这句有问题,经测试是设置grid的高度,并不是单元格的高度)
setGridWidth new_width,
shrink
jqGrid object 动态设置表格的宽度。参数说明如下
  • new_width :表格宽度(单位px)
  • shrink (true or false) :和jqGrid配置shrinkToFit有一样的行为效果,参考:jqGrid选项配置,如果没有配置,将使用jqGrid配置的shrinkToFit.
setLabel colname,
data,
class,
properties
jqGrid object 设置某列的表头标签内容。也可以设置此表头的属性和样式,参数说明如下
  • colname :列名称(来自colModel的name值,也可以为数字,列下标,从0开始,注意列下标为表格中,不是colModel的。)
  • data :如果为空字符串,表头内容保持不变
  • class :如果为字符串值,通过addClass方法给表头增加一个样式;如果为键值对对象,设置表头css.style属性(键名称为样式名称,值为样式值)。
  • properties :设置表头标签的属性(键值对对象)
setRowData rowid,
data,
cssprop
true on success,
false otherwise
更新指定数据行id的数据,data数据格式如 {name1:value1,name2: value2…} ,name来自colModel中name值。
cssprop为字符串值,通过addClass方法给此行增加一个样式;如果为键值对对象,设置此行(TR)css.style属性(键名称为样式名称,值为样式值)。
可以设置行的样式和属性,而不一定需要设置内容,此时data可以设置为false。
注意此行或者此行的单元格不能再编辑模式下,否则将会使用data覆盖输入元素。
setSelection rowid,
onselectrow
jqGrid object 切换指定数据行id的选择状态。如果onselectrow 设置为true(也是默认值),将会触发onSelectRow事件,否则不会。
showCol colname jqGrid object 显示colname(来自colModel配置的name值)指定的列。如果传递列名称数组,如['name1','name2'...],将会显示数组中指定的列,这些值需要来自colModel配置的name值。这个方法不修改表格的宽度。
trigger("reloadGrid") none none 使用当前配置重新加载jqGrid。如果datatype为xml或者json,将会向服务器发送新请求。这个方法需要在已经调用jqGrid构造过的DOM对象上。注意这个方法不会修改HEADER信息,就是说colModel即使被修改了也不会使用colModel的新配置,需要使用GridUnload重新加载不同的(修改过的)colModel。
此方法仅在jqGrid配置loadonce: false 时有效。

 

unbindKeys none jqGrid object 溢出bindKeys方法中定义的事件
updateColumns none none 这个将表头宽度和数据同步。当表格拖放时比较有用,示例如下
var mygrid=jQuery("#grid_id")//[0];//官网的代码还真多错误
mygrid.updateColumns();

通用函数和配置

这些函数可以在任何工程中使用,和jqGrid对象没有关系,语法如下

jQuery.jgrid.jqGridFunction( parameter1,...parameterN );

示例说明

  • jgrid.jqGridFunction :函数
  • parameter1,…parameterN:参数列表

 

注意名字空间为jgrid

函数/配置 参数 返回值 描述
ajaxOptions empty object none 设置jqGrid全局ajax请求配置。这个配置可以重写某些模块单枪的的所有ajax请求。 3.6+版本我们有3层ajax设置。
第一层对模块使用的ajax,第二层由option配置决定,第三层可以通过传递给某些方法的参数来决定。第三层的ajax配置等级最高,使用以下的规则来配置ajax请求。
j
Query.extend(jQuery.ajax({method specific options}, ajaxOptions, ThirdLevelajaxSettinds));
附加的,我们可以定义每个ajax请求的序列化函数,这个函数允许转换传递给服务器的参数。
jqID string parsed string 使用双斜杠(\\)转义特殊的字符,因此单斜杠可以放到字符串中,使jQuery选择器能够正确解析。(Escapes the special string characters with two backslashes (\\) so that a single backslash will be put into the string and can be interpreted correct when used in jQuery selector.),简单来说就是从一个字符串生成正确的jQuery选择器。
jQuery.jgrid.jqID("ab'c")//==>ab\'c,长度是5注意,不是对'转义
jQuery.jgrid.jqID("ab\"c")//==>ab\"c  ,长度是5注意,不是对"转义
jgrid.htmlDecode string decoded_string 将html编码过的字符串还原为原始的html代码(例如&lt;和&gt;转换为<>)
jgrid.htmlEncode string encoded_string 将html字符串编码为对应实体(例如<>转换为&lt;和&gt;)
jgrid.format string formated_string 简单的字符串模板。第一个参数为字符串模板,第二个参数可选,如果设置了,将会替换第一个参数中的占位符(placeholders)。示例
jQuery.jqgformat("Please enter a value between {0} and {1}.", 4, 8)//=>  Please enter a value between 4 and 8.
jgrid.getCellIndex cell index 此方法用于修正IE7-的bug,Cellndex(单元格列下标)用于计算显示循序,而非实际的列下标。
cell为单元格内容,既td元素
jgrid.stringToDoc xmlstring xmlDoc xmlstring 转换为xml dom。返回 xmlDoc (dom document)
jgrid.stripHtml content new_content 删除参数中的html代码,demo
$.jgrid.stripHtml('<a href="#">abc</a>')//=========>abc
jgrid.parse jsonString object 将json格式的字符串转换为json对象或数组。
为了防止javascript劫持攻击(To prevent JavaScript hijacking attacks),推荐web程序开发人员使用这个功能。 返回json对象。
环状结构可以被检查到并安全中断,但是不能更进一步还原(Cyclic structures are detected and safely interrupted, but could not be further restored.)
1,while(1)语句被放在jsonstring的开始(The while(1); construct, located at the beginning of JSON text,)
2,字符串前后有注释( Comments at the beginning and end of the text.)
推荐json数据提供者使用下面的1个或者2个方法防治数据执行,json响应应该如下面这样
while(1);/*{[
{"name":"safe value 1"},
{"name":"safe value 2"}, …
]}*/
设置为json时jqGrid通过此方法获取数据

附加的jqGrid方法

要使用这些方法,你需要在下载页面勾选 Custom后再下载jqGrid,下载地址:http://www.trirand.com/blog/?page_id=6。这些方法包含在grid.custom.js文件中。这些方法属于jqGrid对象的方法,不是通用方法。

Method Parameters Returns Description
filterGrid grid_id,
params
HTML object 这个方法为grid构造一个自定义查询表单,不一定对grid应用,只要是一个有有效的html对象就行。
grid_id :应用查询的grid的id
parms :键值对(参考下面),更多信息参考: custom searching
filterToolbar params jqGrid object 和 filterGrid一样,只是查询输入元素放在grid的表头元素下。当表头元素调整大小后,查询元素也会依据新宽度自动调整。另外一个和 filterGrid的区别就是filterToolbar使用colModel中的定义,更多信息参考:Toolbar searching
getColProp colname array{} 获取指定colModel中指定列名称的属性
GridDestroy grid_id true on success,
false otherwise
从DOM中销毁指定id的grid对象(清除和这个grid对象有关的html代码和移除所有绑定的事件)
GridUnload grid_id true on success,
false otherwise
这个和GridDestroy差不多,只是table和pager元素没有被删除,可以重新使用。
setGridState state jGrid object 通过state参数来设置隐藏或者显示grid。 state 设置为 'visible' 将显示grid,设置为‘hidden'将隐藏grid。注意这个方法没调用onHeaderClick事件,grid标题层仍然是可见的。
setColProp colname,
properties
jGrid object 设置colModel的新属性,这个方法的目的是为了动态的修改列的属性。但是对某些属性没有作用,参考:jqGrid colModel配置参数
jQuery("#grid_id").setColProp('colname',{editoptions:{value:"True:False"}});
sortGrid colname,
reload
jqGrid object 按照给定的列名称重新排列和设置对应的图标。也可以通过setGridParam({sortname:'myname'}).trigger('reloadGrid')来实现(不会设置排序图标)。reload设置为true,jqGrid以当前页和排序设置重新加载。
updateGridRows data,
rowidname,
jsonreader
true on success,
false otherwise
通过给定的rowidname更新jqgrid中存在的数据。This method update the existing data in the grid by given rowidname.
data :数据,格式如[{name:value,name1:value1…}, {name:value,name2:value2…}],name来自colModel配置的name值。不需要包含每列的数据(和setRowData方法一样)
rowidname (string):data数组项中的那个键名称作为id键,如果不设置,则默认为“id”
jsonreader (boolean) :默认false。设置为true,将定义一个jsonReader来设置数据。注意这个仅当jsonReader对象的repeatitems被设置为true时有效,此时数据将不是键值对,为数组并且和colModel定义的列数一致。(.In this case the data should be not in pair name:value, but only values where the number of columns should be equal of those in colModel.)

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

 



原创文章,转载请注明出处:jqGrid方法
评论(0)Web开发网
阅读(3121)喜欢(0)不喜欢(0)jqGrid中文API