jQuery EasyUI 數據網格與樹插件 - Datagrid 數據網格


jQuery EasyUI 插件 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 插件 jQuery EasyUI 插件