jQuery學習之：jqGrid表格插件——參數配置

因爲jqGrid功能強大，配置比較複雜，在第一個例子中，對於jqGrid的配置參數沒有進行什麼解釋。從如今開始，會陸續介紹jqGrid的參數。這 些參數的詳細介紹請查看官方文檔。因爲本人英語水平有限，翻譯很差，請多原諒。（爲了保證連貫性，翻譯時引用了 http://a3mao.javaeye.com，在此感謝。但在他的基礎上增長了一些內容。）

a3mao永久域名 http://a3mao.javaeye.com

上有不少jqGrid的API，你們能夠查看。

在$("#tableId").jqGrid(optional);中，optional對象包含以下的屬性：（屬性按字母順序排列）

參數名稱	類型	描述	默認值	是否能夠被修改
ajaxGridOptions	object	對ajax參數進行全局設置，能夠覆蓋ajax事件：error，complete 和 beforeSend	空值	是
ajaxGridOptions	object	對ajax參數進行全局設置	空值	是
ajaxSelectOptions	object	對ajax的select參數進行全局設置，設置editoptions跟searchoptions 參數的select屬性值	空值	是
altclass	String	用於表格行交替變色的class屬性。你能夠定義本身的class來替代默認值。只有當altRows屬性設置爲true時，該屬性才起做用	ui-priority-secondary	是，但須要從新加載
altRows	boolean	設置表格是否容許行交替變色值	false	是，需從新加載
autoencode	boolean	當爲 ture 時對url進行編碼	false	是
autowidth	boolean	若是爲ture時，則當表格在首次被建立時會根據父元素比例從新調整表格寬度。若是父元素寬度改變，爲了使表格寬度可以自動調整則須要實現函數：setGridWidth	false	否
caption	String	定義表格名稱	空值	否，可是能夠用api修改
cellLayout	integer	定義了單元格padding + border 寬度。一般沒必要修改此值。初始值爲5，paddingLef?2+paddingRight?2+borderLeft?1=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）或者從右向左（rtr）。	ltr	否
editurl	string	定義對form編輯時的url	空值	是
emptyrecords	string	當返回的數據行數爲0時顯示的信息。只有當屬性 viewrecords 設置爲ture時起做用	在語言包中	是
ExpandColClick	boolean	當爲true時，點擊展開行的文本時，treeGrid就能展開或者收縮，不只僅是點擊圖片	true	否
ExpandColumn	string	指定那列來展開tree grid，默認爲第一列，只有在treeGrid爲true時起做用	空值	否
footerrow	boolean	當爲true時，會在翻頁欄之上增長一行	false	否
forceFit	boolean	當爲ture時，調整列寬度不會改變表格的寬度。當shrinkToFit 爲false時，此屬性會被忽略	false	否
gridstate	string	定義當前表格的狀態：'visible' or 'hidden'	visible	否
gridview	boolean	構造一行數據後添加到grid中，若是設爲true則是將整個表格的數據都構造完成後再添加到grid中，但treeGrid, subGrid, or afterInsertRow 不能用	false	是
height	mixed	表格高度，能夠是數字，像素值或者百分比	150	否
hiddengrid	boolean	當爲ture時，表格不會被顯示，只顯示錶格的標題。只有當點擊顯示錶格的那個按鈕時纔會去初始化表格數據。只有當caption 屬性不爲空並且hidegrid爲ture時才起做用	false	否
hidegrid	boolean	啓用或者禁用控制表格顯示、隱藏的按鈕，只有當caption 屬性不爲空時起效	true	否
hoverrows	boolean	當爲false時mouse hovering會被禁用	false	是
jsonReader	array	描述json指望數據格式的數組。		否
lastpage	integer	只讀屬性，定義了總頁數	0	否
lastsort	integer	只讀屬性，定義了最後排序列的索引，從0開始	0	否
loadonce	boolean	若是爲ture則數據只從服務器端抓取一次，以後全部操做都是在客戶端執行，翻頁功能會被禁用	false	否
loadtext	string	當請求或者排序時所顯示的文字內容	Loading....	否
loadui	string	當執行ajax請求時要幹什麼。 disable禁用ajax執行提示； enable默認，當執行ajax請求時的提示； block啓用Loading提示，可是阻止其餘操做	enable	是
mtype	string	請求的類型：(「POST」 or 「GET」)	GET	是
multikey	string	只有在multiselect設置爲ture時起做用，定義使用那個key來作多選。 shiftKey， altKey， ctrlKey	空值	是
multiboxonly	boolean	只有當multiselect = true.起做用，當multiboxonly 爲ture時只有選擇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 valuesprmNames: {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爲ture時才能起效，且總記錄數大於0時纔會顯示此信息	語言包	是
resizeclass	string	定義一個class到一個列上用來顯示列寬度調整時的效果	空值	否
rowList	array[]	一個數組用來調整表格顯示的記錄數，此參數值會替代rowNum參數值傳給服務器端。若是爲空則不顯示，設置格式：[10,20,30]。	[]	否
rownumbers	boolean	若是爲ture則會在表格左邊新增一列，顯示行順序號，從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	此屬性用來講明當初始化列寬度時候的計算類型，若是爲ture，則按比例初始化列寬度。若是爲false，則列寬度使用colModel指定的寬度	true	否
sortable	boolean	是否可排序	false	否
sortname	string	排序列的名稱，此參數會被傳到後臺	空字符串	是
sortorder	string	排序順序，升序或者降序（asc or desc）	asc	是
subGrid	boolean	是否使用suggrid	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放到底部，用法：若是userData的值與colModel的值相同，那麼此列就顯示正確的值，若是不等那麼此列就爲空	false	是
viewrecords	boolean	是否要顯示總記錄數	false	否
viewsortcols	array	定 義排序列的外觀跟行爲。數據格式：[false,'vertical',true].第一個參數是說，是否都要顯示排序列的圖標，false就是隻顯示當 前排序列的圖標；第二個參數是指圖標如何顯示，vertical：排序圖標垂直放置，horizontal：排序圖標水平放置；第三個參數指單擊功 能，true：單擊列可排序，false：單擊圖標排序。說明：若是第三個參數爲false則第一個參數必須爲ture不然不能排序		否
width	number	若是設置則按此設置爲主，若是沒有設置則按colModel中定義的寬度計算	none	否
xmlReader	array	對xml數據結構的描述		否

另外 http://a3mao.javaeye.com 還列出了經常使用的參數。以下：

url	獲取數據的地址
datatype	從服務器端返回的數據類型，默認xml。可選類型：xml，local，json，jsonnp，script，xmlstring，jsonstring，clientside
mtype	ajax提交方式。POST或者GET，默認GET
colNames	列顯示名稱，是一個數組對象。
colModel	對顯示列屬性的設置，是一個數組對象。經常使用到的屬性： name 列顯示的名稱； index 傳到服務器端用來排序用的列名稱； width 列寬度； align 對齊方式； sortable 是否能夠排序
pager	定義翻頁用的導航欄，必須是有效的html元素。翻頁工具欄能夠放置在html頁面任意位置
rowNum	在grid上顯示記錄條數，這個參數是要被傳遞到後臺
rowList	一個下拉選擇框，用來改變顯示記錄數，當選擇時會覆蓋rowNum參數傳遞到後臺
sortname	默認的排序列。能夠是列名稱或者是一個數字，這個參數會被提交到後臺
viewrecords	定義是否要顯示總記錄數
caption	表格名稱

 

另外，「是否能夠被修改」的意思是：在表格建立後，參數是否可以或不可以被修改。換言之，在表格中的初始默認值可否被修改。

設置全局參數：

有時，咱們想改變參數的默認值，且但願這種改變可以同時運用於多個表格。此時，咱們可使用jQuery的extend函數實現。

這裏給一個例子：假設你想有一個行交替變色的表格，且但願全部的表格都是如此，而且，你不想每次（每構建一個表格）都配置相同的參數。這時你可使用這種方式，只需配置一次便可。

< !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" />
< 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" />
< style >
html, body {
        margin: 0;
        padding: 0;
        font-size: 75%;
}
</style>
< 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 src ="js/jquery.jqGrid.min.js" type ="text/javascript" > </script>
< script type ="text/javascript" >
// Here we set a globally the altRows option
jQuery.extend(jQuery.jgrid.defaults, { altRows:true });
</script>
< script type ="text/javascript" >
jQuery(document).ready(function(){
    jQuery("#list").jqGrid({
        url:'example.php',
...

你也能夠增長其餘你想設置的參數。

覆蓋全局參數：

在上面的例子中，咱們學習瞭如何爲你的應用程序中全部的表格設置共用的參數。然而，有些表格可能須要用其餘的參數值，即須要對咱們上，面設置的全局參數進行改變，以用於特定的表格。這時，咱們能夠把相應的參數改過來，即在特定的表格從新配置一次相應的屬性。例如：

< !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" />
< 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" />
< style >
html, body {
        margin: 0;
        padding: 0;
        font-size: 75%;
}
</style>
< 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 src ="js/jquery.jqGrid.min.js" type ="text/javascript" > </script>
< script type ="text/javascript" >
// Here we set a globally the altRows option
jQuery.extend(jQuery.jgrid.defaults, { altRows:true });
</script>
< script type ="text/javascript" > jQuery(document).ready(function(){     jQuery("#list").jqGrid({         url:'example.php',         // here we do not want zebra for this grid         altRows: false, ...