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數據