DIV CSS 佈局教程網

jQuery 學習筆記:jqGrid 從入門到實戰(分頁與搜索全解析)
編輯:JQuery入門技巧     

jqGrid 是一款功能強大的 jQuery 表格插件,它能讓前端頁面與後端數據之間的 Ajax 異步通訊變得輕鬆寫意。本文整理了自己在日常開發中使用 jqGrid 的心得,涵蓋環境配置、取值技巧、自定義分頁、搜索實現,以及一份詳盡的屬性、事件與方法速查表。

一、環境準備:需要引入的文件

想要運行 jqGrid,第一步就是在頁面中引入對應的 CSS 與 JS 資源。

1. 樣式表

 <link href="/css/ui.jqgrid.css" rel="stylesheet" type="text/css" /> 

2. 腳本文件

 <script src='/Scripts/js/jquery-2.0.3.min.js' type="text/javascript"></script> <script src='/Scripts/js/jqGrid/jquery.jqGrid.min.js' type="text/javascript"></script> <script src='/Scripts/js/jqGrid/i18n/grid.locale-en.js' type="text/javascript"></script>

二、使用要點詳解

1. 各類取值的姿勢

(1)獲取單個選中行的 ID

直覺上我們會這樣取得當前行號:

 var rowid = $("#grid-table").jqGrid("getGridParam", "selrow");

但實測發現這招並不靠譜——當你連續點擊同一行時,反而取不到行號了。於是我改用的做法是:在腳本最外層聲明一個變量 selId,並在選中行的回調裡為它賦值:

 onSelectRow: function (rowid, status) { selId = rowid; //給最外層的 selId 賦值 }

(2)獲取多個選中行的 ID

 var ids=$('#gridTable').jqGrid('getGridParam','selarrrow');

返回值是逗號分隔的字符串,形如:

1,2,3,4,5

(3)取得所有行的 ID 數組

 var ids = $("jqgridtableid").jqGrid('getDataIDs'); 

(4)讀取行數據

想拿到選中行的數據,只要把 rowId 傳進去即可:

 var rowData = $('#gridTable').jqGrid('getRowData',rowId); 

此時 rowData 是一個對象,若要取其中某個屬性(例如 name),寫法如下:

 var Name= rowData.name;

(5)讀取單元格數據

 var celldata = $("jqgridtableid").jqGrid('getCell',id,colnum); 

(6)設置行選中狀態

 //設置選中行,支持多行選中: $("jqgridtableid").jqGrid('setSelection',id1); $("jqgridtableid").jqGrid('setSelection',id2);

2. 自定義分頁與數據交互

所謂「自定義」,就是允許你用自己喜歡的 JS 對象格式與後端打交道,最典型的就是 jsonReader。這裡有個坑要特別注意:如果 id 字段設置錯了,jqGrid 會自動拿行號當主鍵,這會直接影響刪除操作——一旦按錯誤的 id 去刪,很可能刪錯行。

 jsonReader: { id: "Id", //相當於設置主鍵 root: "JsonArray", //Json 數據 total: "TotalPage", //總頁數 page: "CurrentPage", //當前頁 records: "TotalRecord",//總記錄數 repeatitems: false },

配置好之後,在 C# 端就能用一個泛型類把分頁信息與數據內容打包,輕鬆與 jqGrid 表格完成交互:

 /// <summary> /// 分頁 ViewModel /// </summary> public class jQGrid<T> where T : class { public jQGrid() { } /// <summary> /// 帶 4 個參數的構造函數 /// </summary> /// <param name="rows">每頁顯示行數</param> /// <param name="currentPage">當前頁</param> /// <param name="totalRecord">結果總記錄數</param> /// <param name="jsonArray">JSON 數據</param> public jQGrid(int rows, int currentPage, int totalRecord, IList<T> jsonArray) { TotalPage = this.CalculateTotalPage(rows, totalRecord); CurrentPage = currentPage; TotalRecord = totalRecord; JsonArray = jsonArray; } public int TotalPage { get; set; } public int CurrentPage { get; set; } public int TotalRecord { get; set; } public IList<T> JsonArray { get; set; } /// <summary> /// 根據每頁顯示數與總記錄數計算出總頁數 /// </summary> /// <param name="rows">每頁顯示數</param> /// <param name="totalRecord">結果總記錄數</param> /// <returns></returns> public int CalculateTotalPage(int rows, int totalRecord) { return Convert.ToInt32(Math.Ceiling((double)totalRecord / (double)rows)); } } 

3. 搜索功能的實現

搜索的核心思路,是借助 jqGrid 的 postData 把查詢條件送到服務器端。

 $("#btnSearch").click(function () { var rules = ""; $("#multipleSearchDialog").each(function (i) { $(".div-padding :input").each(function () { if ($(this).val()) { rules += '"' + $(this).attr("name") + '":"' + $(this).val() + '"'; } }) }); ParamJson = '{' + rules + '}'; var postData = $("#grid-table").jqGrid("getGridParam", "postData"); $.extend(postData, { Param: ParamJson }); $("#grid-table").jqGrid("setGridParam", { search: true }).trigger("reloadGrid", [{ page: 1}]); //重載 JQGrid }); 

後端只需接收參數並反序列化,即可拿到查詢條件的鍵值對:

 Dictionary<string, string> DicParam = new Dictionary<string, string>(); string Param = Convert.ToString(Request["Param"]); if (!string.IsNullOrEmpty(Param)) { System.Web.Script.Serialization.JavaScriptSerializer sr = new System.Web.Script.Serialization.JavaScriptSerializer(); DicParam = sr.Deserialize(Param, typeof(Dictionary<string, string>)) as Dictionary<string, string>; } 

拿到這組鍵值對之後,通常就是拼進 SQL 的 where 子句裡使用。

三、常用配置屬性速查

下表整理了 jqGrid 使用過程中經常打交道的屬性:

參數名稱 類型 描述 默認值 是否可以被修改 ajaxGridOptions object 對 ajax 參數進行全局設置,可以覆蓋 ajax 事件:error、complete 和 beforeSend 空值 是 altclass String 用於表格行交替變色的 class 屬性。你可以定義自己的 class 來替代默認值。只有當 altRows 屬性設置為 true 時,該屬性才起作用 ui-priority-secondary 是,但需要重新加載 altRows boolean 設置表格是否允許行交替變色值 false 是,需重新加載 autoencode boolean 當為 true 時對 url 進行編碼 false 是 autowidth boolean 如果為 true 時,則當表格首次被創建時會根據父元素比例重新調整表格寬度。如果父元素寬度改變,為了使表格寬度能夠自動調整則需要實現函數:setGridWidth false 否 caption String 定義表格名稱 空值 否,但是可以用 api 修改 cellLayout integer 定義了單元格 padding + border 寬度。通常不必修改此值。初始值為 5 5 否 cellEdit boolean 啟用或者禁用單元格編輯功能 false 是 cellsubmit String 定義了單元格內容保存位置:"remote"、"clientArray" 'remote' 是 cellurl String 單元格提交的 url 空值 是 colModel array 對顯示列屬性的設置,是一個數組對象。常用到的屬性:name 列顯示的名稱;index 傳到服務器端用來排序用的列名稱;width 列寬度;align 對齊方式;sortable 是否可以排序 空值 否 colNames array[] 放置列名稱的數組,必須與 colModel 大小相同 空數組 否 datastr String xmlstring 或者 jsonstring 空值 是 datatype string 從服務器端返回的數據類型(表格期望接收的數據類型)。可選類型:xml、xmlstring、json、local、function xml 是 deselectAfterSort boolean 只有當 datatype 為 local 時起作用。當排序時不選擇當前行 true 是 direction string 表格中文字的顯示方向,從左向右(ltr)或者從右向左(rtl) ltr 否 editurl string 定義對 form 編輯時的 url 空值 是 emptyrecords string 當返回的數據行數為 0 時顯示的信息。只有當屬性 viewrecords 設置為 true 時起作用 在語言包中 是 ExpandColClick boolean 當為 true 時,點擊展開行的文本時,treeGrid 就能展開或者收縮,不僅僅是點擊圖片 true 否 ExpandColumn string 指定那列來展開 tree grid,默認為第一列,只有在 treeGrid 為 true 時起作用 空值 否 footerrow boolean 當為 true 時,會在翻頁欄之上增加一行 false 否 forceFit boolean 當為 true 時,調整列寬度不會改變表格的寬度。當 shrinkToFit 為 false 時,此屬性會被忽略 false 否 gridstate string 定義當前表格的狀態:'visible' 或 'hidden' visible 否 gridview boolean 構造一行數據後添加到 grid 中,如果設為 true 則是將整個表格的數據都構造完成後再添加到 grid 中,但 treeGrid、subGrid 或 afterInsertRow 不能用 false 是 height mixed 表格高度,可以是數字、像素值或者百分比 150 否 hiddengrid boolean 當為 true 時,表格不會被顯示,只顯示表格的標題。只有當點擊顯示表格的那個按鈕時才會去初始化表格數據。只有當 caption 屬性不為空而且 hidegrid 為 true 時才起作用 false 否 hidegrid boolean 啟用或者禁用控制表格顯示、隱藏的按鈕,只有當 caption 屬性不為空時起效 true 否 hoverrows boolean 當為 false 時 mouse hovering 會被禁用 false 是 jsonReader array 描述 json 期望數據格式的數組 否 lastpage integer 只讀屬性,定義了總頁數 0 否 lastsort integer 只讀屬性,定義了最後排序列的索引,從 0 開始 0 否 loadonce boolean 如果為 true 則數據只從服務器端抓取一次,之後所有操作都是在客戶端執行,翻頁功能會被禁用 false 否 loadtext string 當請求或者排序時所顯示的文字內容 Loading.... 否 loadui string 當執行 ajax 請求時要干什麼。disable 禁用 ajax 執行提示;enable 默認,當執行 ajax 請求時的提示;block 啟用 Loading 提示,但是阻止其他操作 enable 是 mtype string 請求的類型:("POST" 或 "GET") GET 是 multikey string 只有在 multiselect 設置為 true 時起作用,定義使用哪個 key 來做多選。shiftKey、altKey、ctrlKey 空值 是 multiboxonly boolean 只有當 multiselect = true 時起作用,當 multiboxonly 為 true 時只有選擇 checkbox 才會起作用 false 是 multiselect boolean 定義是否可以多選 false 否 multiselectWidth integer 當 multiselect 為 true 時設置 multiselect 列寬度 20 否 page integer 設置初始的頁碼 1 是 pager mixed 指定分頁欄對象,必須為一個有效的 html 元素。可以是 'pager'、'#pager'、jQuery('#pager'),推薦用 '#pager' 空值 否 pagerpos string 指定分頁欄的位置 center 否 pgbuttons boolean 是否顯示翻頁按鈕 true 否 pginput boolean 是否顯示跳轉頁面的輸入框 true 否 pgtext string 當前頁信息 語言包中設置 是 prmNames array Default values prmNames: {page:"page",rows:"rows", sort: "sidx",order: "sord", search:"_search", nd:"nd", npage:null} 當參數為 null 時不會被發到服務器端 none 是 postData array 此數組內容直接賦值到 url 上,參數類型:{name1:value1…} 空 array 是 reccount integer 只讀屬性,定義了 grid 中確切的行數。通常情況下與 records 屬性相同,但有一種情況例外,假如 rowNum=15,但是從服務器端返回的記錄數是 20,那麼 records 值是 20,但 reccount 值仍然為 15,而且表格中也只顯示 15 條記錄 0 否 recordpos string 定義了記錄信息的位置:left、center、right right 否 records integer 只讀屬性,定義了返回的記錄數 none 否 recordtext string 顯示記錄數信息。{0} 為記錄數開始,{1} 為記錄數結束。viewrecords 為 true 時才能起效,且總記錄數大於 0 時才會顯示此信息 語言包 是 resizeclass string 定義一個 class 到一個列上用來顯示列寬度調整時的效果 空值 否 rowList array[] 一個數組用來調整表格顯示的記錄數,此參數值會替代 rowNum 參數值傳給服務器端。如果為空則不顯示,設置格式:[10,20,30]。 [] 否 rownumbers boolean 如果為 true 則會在表格左邊新增一列,顯示行順序號,從 1 開始遞增。此列名為 'rn'。 false 否 rowNum integer 設置表格中顯示的記錄數,參數會被自動傳到後台。如果此參數設為 10,但是從服務器端返回 15 條記錄,那麼在表格中只會顯示 10 條記錄。如果設為 -1 則禁用此檢查 20 是 rownumWidth integer 如果 rownumbers 為 true,則可以設置 column 的寬度 25 否 savedRow array 只讀屬性,只用在編輯模式下保存數據 空值 否 scroll boolean or integer 創建一個動態滾動的表格,當為 true 時,翻頁欄被禁用,使用垂直滾動條加載數據,且在首次訪問服務器端時將加載所有數據到客戶端。當此參數為數字時,表格只控制可見的幾行,所有數據都在這幾行中加載 false 否 scrollOffset integer 設置垂直滾動條寬度 18 否 scrollrows boolean 當為 true 時讓所選擇的行可見 false 是 selarrrow array-[] 只讀屬性,用來存放當前選擇的行 empty array [] 否 selrow string 只讀屬性,最後選擇行的 id null 否 shrinkToFit boolean 此屬性用來說明當初始化列寬度時候的計算類型,如果為 true,則按比例初始化列寬度。如果為 false,則列寬度使用 colModel 指定的寬度 true 否 sortable boolean 是否可排序 false 否 sortname string 排序列的名稱,此參數會被傳到後台 空字符串 是 sortorder string 排序順序,升序或者降序(asc 或 desc) asc 是 subGrid boolean 是否使用 subgrid false 否 subGridModel array-[] subgrid 模型 empty array 否 subGridType mixed 如果為空則使用表格的 dataType null 是 subGridUrl string 加載 subgrid 數據的 url,jqGrid 會把每行的 id 值加到 url 中 空值 是 subGridWidth integer subgrid 列的寬度 20 否 toolbar array 表格的工具欄。數組中有兩個值,第一個為是否啟用,第二個指定工具欄位置(相對於 body layer),如:[true,"both"]。工具欄位置可選值:"top"、"bottom"、"both"。如果工具欄在上面,則工具欄 id 為 "t_"+表格 id;如果在下面則為 "tb_"+表格 id;如果只有一個工具欄則為 "t_"+表格 id [false,''] 否 totaltime integer 只讀屬性,計算加載數據的時間。目前支持 xml 跟 json 數據 0 否 treedatatype mixed 數據類型,通常情況下與 datatype 相同,不會變 null 否 treeGrid boolean 啟用或者禁用 treegrid 模式 false 否 treeGridModel string treeGrid 所使用的方法 nested 否 treeIcons array 樹的圖標,默認值:{plus:'ui-icon-triangle-1-e',minus:'ui-icon-triangle-1-s',leaf:'ui-icon-radio-off'} 否 treeReader array 擴展表格的 colModel 且加在 colModel 定義的後面 否 tree_root_level numeric root 元素的級別,0 否 url string url null 是 userData array 從 request 中取得的一些用戶信息 empty array 否 userDataOnFooter boolean 當為 true 時把 userData 放到底部 false 是 viewrecords boolean 是否要顯示總記錄數 false 否 viewsortcols array 定義排序列的外觀跟行為。數據格式:[false,'vertical',true]。第一個參數是說,是否都要顯示排序列的圖標,false 就是只顯示當前排序列的圖標;第二個參數是指圖標如何顯示,vertical:排序圖標垂直放置,horizontal:排序圖標水平放置;第三個參數指單擊功能,true:單擊列可排序,false:單擊圖標排序。說明:如果第三個參數為 false 則第一個參數必須為 true 否則不能排序 否 width number 如果設置則按此設置為主,如果沒有設置則按 colModel 中定義的寬度計算 none 否 xmlReader array 對 xml 數據結構的描述 否

此外,url(獲取數據的地址)、datatype(服務器端返回的數據類型,默認 xml)、mtype(ajax 提交方式)、colNames 與 colModel(列相關配置)、pager(翻頁導航欄)、rowNum(每頁顯示記錄條數)、rowList(改變顯示記錄數的下拉框)、sortname(默認排序列)、viewrecords(是否顯示總記錄數)、caption(表格名稱)等,也都是高頻使用的屬性。

四、事件與方法速查

jqGrid 提供了豐富的事件,例如 afterInsertRow(插入行後觸發)、beforeRequest(數據請求前觸發)、beforeSelectRow(選中行前觸發,返回布爾值決定是否選中)、gridComplete(數據裝載完成後觸發)、loadComplete(每次服務器請求後觸發)、loadError(請求失敗時觸發)、onCellSelect(點擊單元格時觸發)、ondblClickRow(雙擊行時觸發)、onSelectRow(行點擊後觸發)、onSelectAll(點擊表頭復選框時觸發)、onSortCol(列排序點擊後、數據排序前觸發)等。

方法方面,常用的有 addJSONData / addXmlData(填充網格)、addRowData / delRowData(增刪行)、getRowData / getCell / getCol(讀取數據)、setRowData / setCell(更新數據)、hideCol / showCol(顯示隱藏列)、setGridParam / setGridWidth / setGridHeight(動態調整)、setSelection / resetSelection(選擇控制)、trigger("reloadGrid")(重新加載網格)等。

五、踩坑記錄

1. IE9 下 jqGrid 一直冒出水平滾動條

根因是 jqGrid 在 IE 下 border 與 padding 疊加導致寬度溢出。可以先試試加上這個屬性:

 cellLayout:0

這樣在頁面縮放為 100% 時滾動條會消失,但縮放比例不為 100% 時仍會出現。要徹底解決,可以直接改 ui.jqgrid.css:

 .ui-jqgrid .ui-jqgrid-bdiv{ overflow-x: hidden; }

若還是不行,也可以用 JS 強制隱藏:

 $(grid_selector).closest(".ui-jqgrid-bdiv").css({ 'overflow-x': 'hidden' }); 

當然,你也可以直接在 .ui-jqgrid-bdiv 樣式中加上 overflow-x:hidden;

2. 自定義操作列

jqGrid 默認的自定義編輯列只能設置編輯按鈕與刪除按鈕,圖標也不太可控。若想自己打造操作列,可以在 actions 列的 formatoptions 中加入自定義格式化函數:

 name: 'myac', index: '', width: 80, fixed: true, sortable: false, resize: false, formatter: 'actions', formatoptions: { keys: true, delbutton:false, delOptions: { recreateForm: true, beforeShowForm: beforeDeleteCallback }, formatter:"actionFormatter" },

接著在頁面開頭擴展 fmatter,寫入你想要的按鈕 HTML:

 $.extend($.fn.fmatter, { actionFormatter: function(cellvalue, options, rowObject) { var retVal = "顯示在原來編輯按鈕那個位置的代碼"; return retVal; } } );

以上就是本次 jqGrid 學習的全部記錄,希望對大家的開發有所幫助。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved