jQuery EasyUI 數據網格與樹插件 - Datagrid 數據網格
jQuery EasyUI 插件
擴展自 $.fn.panel.defaults。通過 $.fn.datagrid.defaults 重寫默認的 defaults。
數據網格(datagrid)以表格格式顯示數據,並為選擇、排序、分組和編輯數據提供了豐富的支持。數據網格(datagrid)的設計目的是為了減少開發時間,且不要求開發人員具備指定的知識。它是羽量級的,但是功能豐富。它的特性包括單元格合併,多列頁眉,凍結列和頁腳,等等。
依賴
- panel
- resizable
- linkbutton
- pagination
用法
從已有的表格元素創建數據網格(datagrid),在 html 中定義列、行及數據。
<table class="easyui-datagrid">
<thead>
<tr>
<th data-options="field:'code'">Code</th>
<th data-options="field:'name'">Name</th>
<th data-options="field:'price'">Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>001</td><td>name1</td><td>2323</td>
</tr>
<tr>
<td>002</td><td>name2</td><td>4612</td>
</tr>
</tbody>
</table>
通過 <table> 標記創建數據網格(datagrid)。嵌套的 <th> 標籤定義表格中的列。
<table class="easyui-datagrid" style="width:400px;height:250px"
data-options="url:'datagrid_data.json',fitColumns:true,singleSelect:true">
<thead>
<tr>
<th data-options="field:'code',width:100">Code</th>
<th data-options="field:'name',width:100">Name</th>
<th data-options="field:'price',width:100,align:'right'">Price</th>
</tr>
</thead>
</table>
也可以使用 javascript 創建數據網格(datagrid)。
<table id="dg"></table>
$('#dg').datagrid({
url:'datagrid_data.json',
columns:[[
{field:'code',title:'Code',width:100},
{field:'name',title:'Name',width:100},
{field:'price',title:'Price',width:100,align:'right'}
]]
});
通過一些參數查詢數據。
$('#dg').datagrid('load', {
name: 'easyui',
address: 'ho'
});
在向伺服器改變數據之後,更新前臺數據。
$('#dg').datagrid('reload'); // reload the current page data
數據網格(DataGrid)屬性
該屬性擴展自面板(panel),下麵是為數據網格(datagrid)添加的屬性。
| 名稱 | 類型 | 描述 | 默認值 |
|---|---|---|---|
| columns | array | 數據網格(datagrid)的列(column)的配置對象,更多細節請參見列(column)屬性。 | undefined |
| frozenColumns | array | 和列(column)屬性一樣,但是這些列將被凍結在左邊。 | undefined |
| fitColumns | boolean | 設置為 true,則會自動擴大或縮小列的尺寸以適應網格的寬度並且防止水準滾動。 | false |
| resizeHandle | string | 調整列的位置,可用的值有:'left'、'right'、'both'。當設置為 'right' 時,用戶可通過拖拽列頭部的右邊緣來調整列。 該屬性自版本 1.3.2 起可用。 |
right |
| autoRowHeight | boolean | 定義是否設置基於該行內容的行高度。設置為 false,則可以提高加載性能。 | true |
| toolbar | array,selector | 數據網格(datagrid)面板的頭部工具欄。可能的值: 1、數組,每個工具選項與鏈接按鈕(linkbutton)一樣。 2、選擇器,只是工具欄。 在 <div> 標籤內定義工具欄:
$('#dg').datagrid({
toolbar: '#tb'
});
<div id="tb">
<a href="#" class="easyui-linkbutton" data-options="iconCls:'icon-edit',plain:true"></a>
<a href="#" class="easyui-linkbutton" data-options="iconCls:'icon-help',plain:true"></a>
</div>
通過數組定義工具欄:
$('#dg').datagrid({
toolbar: [{
iconCls: 'icon-edit',
handler: function(){alert('edit')}
},'-',{
iconCls: 'icon-help',
handler: function(){alert('help')}
}]
});
|
null |
| striped | boolean | 設置為 true,則把行條紋化。(即奇偶行使用不同背景色) | false |
| method | string | 請求遠程數據的方法(method)類型。 | post |
| nowrap | boolean | 設置為 true,則把數據顯示在一行裏。設置為 true 可提高加載性能。 | true |
| idField | string | 指示哪個字段是標識字段。 | null |
| url | string | 從遠程站點請求數據的 URL。 | null |
| data | array,object | 要加載的數據。該屬性自版本 1.3.2 起可用。 代碼實例:
$('#dg').datagrid({
data: [
{f1:'value11', f2:'value12'},
{f1:'value21', f2:'value22'}
]
});
|
null |
| loadMsg | string | 當從遠程站點加載數據時,顯示的提示消息。 | Processing, please wait … |
| pagination | boolean | 設置為 true,則在數據網格(datagrid)底部顯示分頁工具欄。 | false |
| rownumbers | boolean | 設置為 true,則顯示帶有行號的列。 | false |
| singleSelect | boolean | 設置為 true,則只允許選中一行。 | false |
| checkOnSelect | boolean | 如果設置為 true,當用戶點擊某一行時,則會選中/取消選中複選框。如果設置為 false 時,只有當用戶點擊了複選框時,才會選中/取消選中複選框。 該屬性自版本 1.3 起可用。 |
true |
| selectOnCheck | boolean | 如果設置為 true,點擊複選框將會選中該行。如果設置為 false,選中該行將不會選中複選框。 該屬性自版本 1.3 起可用。 |
true |
| pagePosition | string | 定義分頁欄的位置。可用的值有:'top'、'bottom'、'both'。 該屬性自版本 1.3 起可用。 |
bottom |
| pageNumber | number | 當設置了 pagination 屬性時,初始化頁碼。 | 1 |
| pageSize | number | 當設置了 pagination 屬性時,初始化頁面尺寸。 | 10 |
| pageList | array | 當設置了 pagination 屬性時,初始化頁面尺寸的選擇列表。 | [10,20,30,40,50] |
| queryParams | object | 當請求遠程數據時,發送的額外參數。 代碼實例:
$('#dg').datagrid({
queryParams: {
name: 'easyui',
subject: 'datagrid'
}
});
|
{} |
| sortName | string | 定義可以排序的列。 | null |
| sortOrder | string | 定義列的排序順序,只能用 'asc' 或 'desc'。 | asc |
| multiSort | boolean | 定義是否啟用多列排序。該屬性自版本 1.3.4 起可用。 | false |
| remoteSort | boolean | 定義是否從伺服器排序數據。 | true |
| showHeader | boolean | 定義是否顯示行的頭部。 | true |
| showFooter | boolean | 定義是否顯示行的底部。 | false |
| scrollbarSize | number | 滾動條寬度(當滾動條是垂直的時候)或者滾動條的高度(當滾動條是水準的時候)。 | 18 |
| rowStyler | function | 返回例如 'background:red' 的樣式。該函數需要兩個參數: rowIndex:行的索引,從 0 開始。 rowData:該行相應的記錄。 代碼實例:
$('#dg').datagrid({
rowStyler: function(index,row){
if (row.listprice>80){
return 'background-color:#6293BB;color:#fff;'; // return inline style
// the function can return predefined css class and inline style
// return {class:'r1', style:{'color:#fff'}};
}
}
});
|
|
| loader | function | 定義如何從遠程伺服器加載數據。返回 false 則取消該動作。該函數有下列參數: param:要傳遞到遠程伺服器的參數對象。 success(data):當檢索數據成功時調用的回調函數。 error():當檢索數據失敗時調用的回調函數。 |
json loader |
| loadFilter | function | 返回要顯示的過濾數據。該函數有一個參數 'data' ,表示原始數據。您可以把原始數據變成標準數據格式。該函數必須返回標準數據對象,含有 'total' 和 'rows' 屬性。 代碼實例:
// removing 'd' object from asp.net web service json output
$('#dg').datagrid({
loadFilter: function(data){
if (data.d){
return data.d;
} else {
return data;
}
}
});
|
|
| editors | object | 定義編輯行時的編輯器。 | predefined editors |
| view | object | 定義數據網格(datagrid)的視圖。 | default view |
列(Column)屬性
數據網格(DataGrid) 的列(Column)是一個數組對象,它的每個元素也是一個數組。元素數組的元素是一個配置對象,它定義了每個列的字段。
代碼實例:
columns:[[
{field:'itemid',title:'Item ID',rowspan:2,width:80,sortable:true},
{field:'productid',title:'Product ID',rowspan:2,width:80,sortable:true},
{title:'Item Details',colspan:4}
],[
{field:'listprice',title:'List Price',width:80,align:'right',sortable:true},
{field:'unitcost',title:'Unit Cost',width:80,align:'right',sortable:true},
{field:'attr1',title:'Attribute',width:100},
{field:'status',title:'Status',width:60}
]]
| 名稱 | 類型 | 描述 | 默認值 |
|---|---|---|---|
| title | string | 列的標題文本。 | undefined |
| field | string | 列的字段名。 | undefined |
| width | number | 列的寬度。如果未定義,則寬度會自動擴展以適應它的內容。沒有定義寬度將會降低性能。 | undefined |
| rowspan | number | 指示一個單元格佔據多少行。 | undefined |
| colspan | number | 指示一個單元格佔據多少列。 | undefined |
| align | string | 指示如何對齊該列的數據,可以用 'left'、'right'、'center'。 | undefined |
| halign | string | 指示如何對齊該列的頭部,可能的值:'left'、'right'、'center'。如果沒有分配值,則頭部對齊方式將與通過 'align' 屬性定義的數據對齊方式一致。該屬性自版本 1.3.2 起可用。 | undefined |
| sortable | boolean | 設置為 true,則允許該列被排序。 | undefined |
| order | string | 默認的排序順序,只能用 'asc' 或 'desc'。該屬性自版本 1.3.2 起可用。 | undefined |
| resizable | boolean | 設置為 true,則允許該列可調整尺寸。 | undefined |
| fixed | boolean | 設置為 true,則當 'fitColumns' 設置為 true 時放置調整寬度。 | undefined |
| hidden | boolean | 設置為 true,則隱藏該列。 | undefined |
| checkbox | boolean | 設置為 true,則顯示複選框。複選框有固定寬度。 | undefined |
| formatter | function | 單元格的格式化函數,需要三個參數: value:字段的值。 rowData:行的記錄數據。 rowIndex:行的索引。 代碼實例:
$('#dg').datagrid({
columns:[[
{field:'userId',title:'User', width:80,
formatter: function(value,row,index){
if (row.user){
return row.user.name;
} else {
return value;
}
}
}
]]
});
|
undefined |
| styler | function | 單元格的樣式函數,返回樣式字串來自定義該單元格的樣式,例如 'background:red' 。該函數需要三個參數: value:字段的值。 rowData:行的記錄數據。 rowIndex:行的索引。 代碼實例:
$('#dg').datagrid({
columns:[[
{field:'listprice',title:'List Price', width:80, align:'right',
styler: function(value,row,index){
if (value < 20){
return 'background-color:#ffee00;color:red;';
// the function can return predefined css class and inline style
// return {class:'c1',style:'color:red'}
}
}
}
]]
});
|
undefined |
| sorter | function | 用於本地排序的自定義字段的排序函數,需要兩個參數: a:第一個字段值。 b:第二個字段值。 代碼實例:
$('#dg').datagrid({
remoteSort: false,
columns: [[
{field:'date',title:'Date',width:80,sortable:true,align:'center',
sorter:function(a,b){
a = a.split('/');
b = b.split('/');
if (a[2] == b[2]){
if (a[0] == b[0]){
return (a[1]>b[1]?1:-1);
} else {
return (a[0]>b[0]?1:-1);
}
} else {
return (a[2]>b[2]?1:-1);
}
}
}
]]
});
|
undefined |
| editor | string,object | 指示編輯類型。當是字串(string)時則指編輯類型,當是對象(object)時則包含兩個屬性: type:字串,編輯類型,可能的類型:text、textarea、checkbox、numberbox、validatebox、datebox、combobox、combotree。 options:對象,編輯類型對應的編輯器選項。 |
undefined |
編輯器(Editor)
通過 $.fn.datagrid.defaults.editors 重寫默認的 defaults。
每個編輯器有下列行為:
| 名稱 | 參數 | 描述 |
|---|---|---|
| init | container, options | 初始化編輯器並且返回目標對象。 |
| destroy | target | 如果必要就銷毀編輯器。 |
| getValue | target | 從編輯器的文本獲取值。 |
| setValue | target , value | 給編輯器設置值。 |
| resize | target , width | 如果必要就調整編輯器的尺寸。 |
例如,文本編輯器(text editor)定義如下:
$.extend($.fn.datagrid.defaults.editors, {
text: {
init: function(container, options){
var input = $('<input type="text" class="datagrid-editable-input">').appendTo(container);
return input;
},
destroy: function(target){
$(target).remove();
},
getValue: function(target){
return $(target).val();
},
setValue: function(target, value){
$(target).val(value);
},
resize: function(target, width){
$(target)._outerWidth(width);
}
}
});
數據網格視圖(DataGrid View)
通過 $.fn.datagrid.defaults.view 重寫默認的 defaults。
視圖(view)是一個對象,它告訴數據網格(datagrid)如何呈現行。該對象必須定義下列函數:
| 名稱 | 參數 | 描述 |
|---|---|---|
| render | target, container, frozen | 當數據加載時調用。 target:DOM 對象,數據網格(datagrid)對象。 container:行的容器。 frozen:指示是否呈現凍結容器。 |
| renderFooter | target, container, frozen | 這是呈現行腳的選項函數。 |
| renderRow | target, fields, frozen, rowIndex, rowData | 這是將會被 render 函數調用的選項函數。 |
| refreshRow | target, rowIndex | 定義如何刷新指定的行。 |
| onBeforeRender | target, rows | 視圖被呈現前觸發。 |
| onAfterRender | target | 視圖被呈現後觸發。 |
事件
該事件擴展自面板(panel),下麵是為數據網格(datagrid)添加的事件。
| 名稱 | 參數 | 描述 |
|---|---|---|
| onLoadSuccess | data | 當數據加載成功時觸發。 |
| onLoadError | none | 加載遠程數據發生某些錯誤時觸發。 |
| onBeforeLoad | param | 發送加載數據的請求前觸發,如果返回 false 加載動作就會取消。 |
| onClickRow | rowIndex, rowData | 當用戶點擊一行時觸發,參數包括: rowIndex:被點擊行的索引,從 0 開始 rowData:被點擊行對應的記錄 |
| onDblClickRow | rowIndex, rowData | 當用戶雙擊一行時觸發,參數包括: rowIndex:被雙擊行的索引,從 0 開始 rowData:被雙擊行對應的記錄 |
| onClickCell | rowIndex, field, value | 當用戶單擊一個單元格時觸發。 |
| onDblClickCell | rowIndex, field, value | 當用戶雙擊一個單元格時觸發。 代碼實例:
// when double click a cell, begin editing and make the editor get focus
$('#dg').datagrid({
onDblClickCell: function(index,field,value){
$(this).datagrid('beginEdit', index);
var ed = $(this).datagrid('getEditor', {index:index,field:field});
$(ed.target).focus();
}
});
|
| onSortColumn | sort, order | 當用戶對一列進行排序時觸發,參數包括: sort:排序的列的字段名 order:排序的列的順序 |
| onResizeColumn | field, width | 當用戶調整列的尺寸時觸發。 |
| onSelect | rowIndex, rowData | 當用戶選中一行時觸發,參數包括: rowIndex:選中行的索引,從 0 開始 rowData:選中行對應的記錄 |
| onUnselect | rowIndex, rowData | 當用戶取消選中一行時觸發,參數包括: rowIndex:取消選中行的索引,從 0 開始 rowData:取消選中行對應的記錄 |
| onSelectAll | rows | 當用戶選中全部行時觸發。 |
| onUnselectAll | rows | 當用戶取消選中全部行時觸發。 |
| onCheck | rowIndex,rowData | 當用戶勾選一行時觸發,參數包括: rowIndex:勾選行的索引,從 0 開始 rowData:勾選行對應的記錄 該事件自版本 1.3 起可用。 |
| onUncheck | rowIndex,rowData | 當用戶取消勾選一行時觸發,參數包括: rowIndex:取消勾選行的索引,從 0 開始 rowData:取消勾選行對應的記錄 該事件自版本 1.3 起可用。 |
| onCheckAll | rows | 當用戶勾選全部行時觸發。該事件自版本 1.3 起可用。 |
| onUncheckAll | rows | 當用戶取消勾選全部行時觸發。該事件自版本 1.3 起可用。 |
| onBeforeEdit | rowIndex, rowData | 當用戶開始編輯一行時觸發,參數包括: rowIndex:編輯行的索引,從 0 開始 rowData:編輯行對應的記錄 |
| onAfterEdit | rowIndex, rowData, changes | 當用戶完成編輯一行時觸發,參數包括: rowIndex:編輯行的索引,從 0 開始 rowData:編輯行對應的記錄 changes:更改的字段/值對 |
| onCancelEdit | rowIndex, rowData | 當用戶取消編輯一行時觸發,參數包括: rowIndex:編輯行的索引,從 0 開始 rowData:編輯行對應的記錄 |
| onHeaderContextMenu | e, field | 當數據網格(datagrid)的頭部被右鍵單擊時觸發。 |
| onRowContextMenu | e, rowIndex, rowData | 當右鍵點擊行時觸發。 |
方法
| 名稱 | 參數 | 描述 |
|---|---|---|
| options | none | 返回選項(options)對象。 |
| getPager | none | 返回分頁(pager)對象。 |
| getPanel | none | 返回面板(panel)對象。 |
| getColumnFields | frozen | 返回列的字段,如果 frozen 設置為 true,則凍結列的字段被返回。 代碼實例:
var opts = $('#dg').datagrid('getColumnFields'); // get unfrozen columns
var opts = $('#dg').datagrid('getColumnFields', true); // get frozen columns
|
| getColumnOption | field | 返回指定列的選項。 |
| resize | param | 調整尺寸和佈局。 |
| load | param | 加載並顯示第一頁的行,如果指定 'param' 參數,它將替換 queryParams 屬性。通常情況下,通過傳遞一些從參數進行查詢,該方法被調用來從伺服器加載新數據。
$('#dg').datagrid('load',{
code: '01',
name: 'name01'
});
|
| reload | param | 重新加載行,就像 load 方法一樣,但是保持在當前頁。 |
| reloadFooter | footer | 重新加載底部的行。代碼實例:
// update footer row values and then refresh
var rows = $('#dg').datagrid('getFooterRows');
rows[0]['name'] = 'new name';
rows[0]['salary'] = 60000;
$('#dg').datagrid('reloadFooter');
// update footer rows with new data
$('#dg').datagrid('reloadFooter',[
{name: 'name1', salary: 60000},
{name: 'name2', salary: 65000}
]);
|
| loading | none | 顯示正在加載狀態。 |
| loaded | none | 隱藏正在加載狀態。 |
| fitColumns | none | 使列自動展開/折疊以適應數據網格(datagrid)的寬度。 |
| fixColumnSize | field | 固定列的尺寸。如果 'field' 參數未設置,所有的列的尺寸將是固定的。 代碼實例:
$('#dg').datagrid('fixColumnSize', 'name'); // fix the 'name' column size
$('#dg').datagrid('fixColumnSize'); // fix all columns size
|
| fixRowHeight | index | 固定指定行的高度。如果 'index' 參數未設置,所有的行的高度將是固定的。 |
| freezeRow | index | 凍結指定的行,以便數據網格(datagrid)向下滾動時這些凍結行總是被顯示在頂部。該方法自版本 1.3.2 起可用。 |
| autoSizeColumn | field | 調整列的寬度以適應內容。該方法自版本 1.3 起可用。 |
| loadData | data | 加載本地數據,舊的行會被移除。 |
| getData | none | 返回加載的數據。 |
| getRows | none | 返回當前頁的行。 |
| getFooterRows | none | 返回底部的行。 |
| getRowIndex | row | 返回指定行的索引,row 參數可以是一個行記錄或者一個 id 字段的值。 |
| getChecked | none | 返回複選框選中的所有行。該方法自版本 1.3 起可用。 |
| getSelected | none | 返回第一個選中的行或者 null。 |
| getSelections | none | 返回所有選中的行,當沒有選中的記錄時,將返回空數組。 |
| clearSelections | none | 清除所有的選擇。 |
| clearChecked | none | 清除所有勾選的行。該方法自版本 1.3.2 起可用。 |
| scrollTo | index | 滾動到指定行。該方法自版本 1.3.3 起可用。 |
| highlightRow | index | 高亮顯示一行。該方法自版本 1.3.3 起可用。 |
| selectAll | none | 選中當前頁所有的行。 |
| unselectAll | none | 取消選中當前頁所有的行。 |
| selectRow | index | 選中一行,行索引從 0 開始。 |
| selectRecord | idValue | 通過傳遞 id 的值做參數選中一行。 |
| unselectRow | index | 取消選中一行。 |
| checkAll | none | 勾選當前頁所有的行。該方法自版本 1.3 起可用。 |
| uncheckAll | none | 取消勾選當前頁所有的行。該方法自版本 1.3 起可用。 |
| checkRow | index | 勾選一行,行索引從 0 開始。該方法自版本 1.3 起可用。 |
| uncheckRow | index | 取消勾選一行,行索引從 0 開始。該方法自版本 1.3 起可用。 |
| beginEdit | index | 開始對一行進行編輯。 |
| endEdit | index | 結束對一行進行編輯。 |
| cancelEdit | index | 取消對一行進行編輯。 |
| getEditors | index | 獲取指定行的編輯器。每個編輯器有下列屬性: actions:編輯器能做的動作,與編輯器定義相同。 target:目標編輯器的 jQuery 對象。 field:字段名。 type:編輯器的類型,比如:'text'、'combobox'、'datebox',等等。 |
| getEditor | options | 獲取指定的編輯器, options 參數包含兩個屬性: index:行的索引。 field:字段名。 代碼實例:
// get the datebox editor and change its value
var ed = $('#dg').datagrid('getEditor', {index:1,field:'birthday'});
$(ed.target).datebox('setValue', '5/4/2012');
|
| refreshRow | index | 刷新一行。 |
| validateRow | index | 驗證指定的行,有效時返回 true。 |
| updateRow | param | 更新指定的行, param 參數包括下列屬性: index:要更新的行的索引。 row:新的行數據。 代碼實例:
$('#dg').datagrid('updateRow',{
index: 2,
row: {
name: 'new name',
note: 'new note message'
}
});
|
| appendRow | row | 追加一個新行。新的行將被添加在最後的位置:
$('#dg').datagrid('appendRow',{
name: 'new name',
age: 30,
note: 'some messages'
});
|
| insertRow | param | 插入一個新行, param 參數包括下列屬性: index:插入進去的行的索引,如果沒有定義,就追加該新行。 row:行的數據。 代碼實例:
// insert a new row at second row position
$('#dg').datagrid('insertRow',{
index: 1, // index start with 0
row: {
name: 'new name',
age: 30,
note: 'some messages'
}
});
|
| deleteRow | index | 刪除一行。 |
| getChanges | type | 獲取最後一次提交以來更改的行,type 參數表示更改的行的類型,可能的值是:inserted、deleted、updated,等等。當 type 參數沒有分配時,返回所有改變的行。 |
| acceptChanges | none | 提交自從被加載以來或最後一次調用 acceptChanges 以來所有更改的數據。 |
| rejectChanges | none | 回滾自從創建以來或最後一次調用 acceptChanges 以來所有更改的數據。 |
| mergeCells | options | 把一些單元格合併為一個單元格,options 參數包括下列特性: index:列的索引。 field:字段名。 rowspan:合併跨越的行數。 colspan:合併跨越的列數。 |
| showColumn | field | 顯示指定的列。 |
| hideColumn | field | 隱藏指定的列。 |
jQuery EasyUI 插件
