jqGrid单元格编辑配置，事件及方法

转自 http://blog.csdn.net/xueshijun666/article/details/18151055

// var ret = $("#in_store_list_details_grid_table").getChangedCells('dirty'); // Returns the changed cells.

// var ret = $("#in_store_list_details_grid_table").getChangedCells('all'); // Return Rows

单元格编辑

单元格编辑提供给用户修改一行中的单个单元格内容的功能，开发者可以通过ajax或者单元格编辑事件对修改的数据进行处理。

通过下面的行为，单元格编辑支持键盘导航和执行单元格编辑操作

1. 点击一个不可编辑的单元格会选中它，然后可以通过上下左右键移动到其他单元格
2. 当移动到一个可编辑的单元格，可以按下Enter键将单元格切换到编辑模式。当再次按下Enter键，或者tab，点击其他单元格将会执行保存操作。按下Esc键取消编辑并且恢复为之前的值。当编辑一个单元格时，光标键始终在此单元格内。
3. 点击可编辑的单元格会切换到编辑模式下
4. 单元格设置有'not-editable-cell'样式时，即使colModel中设置过此列为可编辑的，也无法编辑此列。
5. 提示：colModel中需要配置列为可编辑，并且指定了edittype才会切换到编辑模式，要不无法切换。

安装

要使用单元格编辑模块，你需要在下载页面勾选Cell editing 和 Common这2个功能，然后再点击 Download 下载按钮下载jqGrid。下载地址：http://www.trirand.com/blog/?page_id=6

要看元代可以从src目录中找到 grid.celledit.js 这个文件

属于单元格编辑的属性，事件和方法是jqGrid选项配置中的一个子集。

属性

单元格编辑的具体属性需要在jqGrid方法中配置。

属性名称	类型	描述	默认值
cellEdit	boolean	是否启用单元格编辑。设置为true，onSelectRow事件不能使用，鼠标悬停也会被禁用（鼠标悬停在行上）	false
cellsubmit	string	配置单元格内容保存位置，可用值'remote' 或者'clientArray' 1）设置为remote，单元格内容改变后将启动ajax请求cellurl配置的地址保存到服务器上。此数据行的id和修改的内容被附加到url上。配置了mtype为post提交，那么将会post提交键值对内容。例如，保存一个名为mycell的单元格 {id: rowid, mycell: cellvalue} 将会作为附加数据附加到url上。 2）设置为clientArray，不会发送ajax请求，修改后内容可以条用getChangedCells方法或者通过事件获取到	remote
cellurl	string	保存数据的url地址。cellsubmit设置为remote时一定要配置url地址。	null
ajaxCellOptions	object	配置保存数据的ajax请求的全局设置。这个配置可以重写所有当前保存数据的ajax请求设置，包括complete事件	empty object

示例

cellsubmit设置为remote，可以使用下面的代码

－收缩JavaScript代码

$('selector').jqGrid({
//其他配置
    'cellEdit' : true,
    'cellsubmit' : 'remote',
    'cellurl' : '/url/to/handling/the/changed/cell/value'
})

cellsubmit设置为clientArray

－收缩JavaScript代码

$('selector').jqGrid({//其他配置    'cellEdit' : true,    'cellsubmit' : 'rclientArray'})

事件

单元格编辑的事件需要在jqGrid方法中配置

下面列出的大部分事件使用下面定义的参数，备注：iRow和iCol经测试值的开始位置不一样。

• rowid - 数据行的id
• cellname-单元格名称（colModel定义的name）
• value - 单元格内容
• iRow - 单元格所在行的行号（注意不要和rowid搞混），iRow从1开始
• iCol - 单元格处于行中的列号，iCol从0开始

事件名称	参数	描述
afterEditCell	rowid, cellname, value, iRow, iCol	单元格被编辑后出发，例如对应的编辑控件元素被添加DOM后
afterRestoreCell	rowid, value, iRow, iCol	调用restoreCell方法或者按ESC键取消编辑后出发
afterSaveCell	rowid, cellname, value, iRow, iCol	单元格成功保存后出发，这是更改其他内容的理想的地方
afterSubmitCell	serverresponse, rowid, cellname, value, iRow, iCol	数据提交到服务器并返回信息后触发。此方法需要返回[success(boolean),message] 类型的数据。 1）返回[true,””] 表示成功保存了单元格内容。 2）返回[false,”Error message”]表示保存单元格内容失败，并且出现一个对话框显示返回的错误信息。 servereresponse为发送请求的ajax对象，返回值的第二个参数可以通过获取serverresponse.responseText 得到服务器返回的信息
beforeEditCell	rowid, cellname, value, iRow, iCol	在编辑单元格前触发
beforeSaveCell	rowid, cellname, value, iRow, iCol	在验证输入数据（如果存在）之前触发。事件可以返回新的内容替换之前的内容。 beforeSaveCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return “new value”; } } new value将替换之前的值
beforeSubmitCell	rowid, cellname, value, iRow, iCol	beforeSubmitCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return {name1:value1,name2:value2} } else { return {} } } 返回的JSON数据将会附加到cellurl提交的数据中。 发送单元格内容到服务器之前触发（cellsubmit配置为remote是有效）。事件可以返回一个新JSON数据一起提交到服务器
errorCell	serverresponse, status	保存数据后动态页出错时触发。 1）servereresponse为ajax对象，可以通过serverresponse.responseText获得服务器返回的信息 2）status为错误号
formatCell	rowid, cellname, value, iRow, iCol	此事件可以在单元格被编辑前格式化单元格内容，返回格式化后的值。
onSelectCell	rowid, celname, value, iRow, iCol	在单元格切换为文本模式后触发
serializeCellData	postdata	如果设置了这个事件，在保存单元格时将序列化传给ajax请求的数据。这个方法需要返回序列化后的内容。当自定义数据需要发送到服务器时可以使用此事件。例如，JSON格式的字符串，XML格式的字符串等等。此事件返回的数据将会提交到服务器。

事件调用循序

取决于cellSubmit配置的值为 'remote' 或者 'clientArray'

下面为cellSubmit设置为remote的循序

1. formatCell (rowid, cellname, value, iRow, iCol) ：切换到编辑模式前可以在这里修改单元格内容作为输入控件的值
2. beforeEditCell (rowid, cellname, value, iRow, iCol) ：在单元格切换到编辑模式前触发事件
3. afterEditCell (rowid, cellname, value, iRow, iCol) ：在单元格对应的输入控件加入DOM中触发事件
4. beforeSaveCell (rowid, cellname, value, iRow, iCol) ：在单元格内容保存前触发，你可以在这个事件里面存储发往服务器的内容
5. beforeSubmitCell (rowid, cellname, value, iRow, iCol) ：在数据发到服务器前触发，此方法可以返回json对象附加额外的数据
6. afterSubmitCell (serverresponse, rowid, cellname, value, iRow, iCol)：保存单元格，服务器返回信息后触发，事件可以返回错误信息弹出显示错误的对话框
7. afterSaveCell (rowid, cellname, value, iRow, iCol) ：单元格成功保存后触发
8. errorCell (serverresponse, status)：当服务器返回非200状态出错时触发 (如403, 404, 500状态等)
9. onSelectCell (rowid, celname, value, iRow, iCol) ：在单元格切换为文本模式后触发

cellSubmit设为 clientArray的循序

1. formatCell (rowid, cellname, value, iRow, iCol) ：切换到编辑模式前可以在这里修改单元格内容作为输入控件的值
2. beforeEditCell (rowid, cellname, value, iRow, iCol)：在单元格切换到编辑模式前触发事件
3. afterEditCell (rowid, cellname, value, iRow, iCol) ：在单元格对应的输入控件加入DOM中触发事件
4. beforeSaveCell (rowid, cellname, value, iRow, iCol)：在单元格内容保存前触发
5. beforeSubmitCell (rowid, cellname, value, iRow, iCol)：你可以保存数据到任何地方，包括自定义ajax发送数据到服务器保存【用ajax时注意ajax为异步的，ajax未返回前就会继续自行下面2个事件，所以下面2个事件要根据ajax结果来进行一些判断的时候，ajax需要指定为同步执行】
6. afterSaveCell (rowid, cellname, value, iRow, iCol) ：beforeSubmitCell成功保存单元格内容后触发
7. onSelectCell (rowid, celname, value, iRow, iCol)：在单元格切换为文本模式后触发

方法

下面所有方法调用需要通过jqGrid的实例并且返回相同的jqGrid实例。jqGrid示例图

方法名称	方法参数	描述
editCell	iRow, iCol, edit	编辑iRow行号iCol列号的单元格。iRow，iCol定义。如果edit参数设置为false仅选中单元格。设置为true选中单元格并且切换到编辑模式
getChangedCells	method	依据method参数（默认值为all）返回修改过的所有行数据（JSON对象数组），设置为dirty，返回的数据包含id和被修改过的数据，未修改过的不返回。 eg，原始数据为[{id:1,name:'showbo1',addr:'桂林'},{id:2,name:'showbo2',addr:'广西桂林'}]，修改id为1的name为showbo csdn，调用此方法 1）不传递method参数或者为all，则返回[{id:1,name:'showbo csdn',addr:'桂林'}}]。 2）method设置为dirty，则返回[{id:1,name:'showbo csdn'}]
restoreCell	iRow, iCol	在编辑模式下，还原iRow行号，iCol列号的单元格。如上图不管输入框输入什么，调用$('selector').restoreCell(3,1)后将会丢弃输入的内容，还原为name3，并且切换为文本模式。
saveCell	iRow, iCol	在编辑模式下，保存iRow行号，iCol列号的单元格内容，并且切换为文本模式

提示

数据如何组成

单元格编辑模式下输入控件结构依照如下规则When the cell is edited and the input elements is created we set the following rules:

• 编辑控件的id为： 'iRow_'+colModel中配置的name值。例如，编辑第20行下某列，colModel中配置此列name配置值为myname，那么输入控件的id为20_myname
• 编辑控件的name为colModel配置中的name值。如上面的示例，name为 myname

提交到服务器的内容

提交到服务器的JSON对象（{}）数据包含

• 输入控件键值对（name:value pair ），name为此单元格中输入对象的name值
• 附加（id:rowid）键值对，rowid为此行对应数据的id
•  beforeSubmitCell事件中返回的非空的JSON数据