easyui datagrid使用參考

數據表格

繼承$.fn.panel.defaults，使用$.fn.datagrid.defaults重載默認值。

依賴關系

• 控制面板
• 縮放
• 鏈接按鈕
• 分頁

使用方法

<table id="tt"></table>

$('#tt').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'}
    ]]
});

數據表格屬性

屬性繼承控制面板，以下是數據表格獨有的屬性。

名稱類型描述默認值

columns（列）	array（數組）	數據表格列配置對象，查看列屬性以獲取更多細節。	null
frozenColumns（固定列）	array（數組）	跟列屬性一樣，但是這些列固定在左邊，不會滾動。	null
fitColumns（自適應列寬）	boolean（布爾型）	設置為true將自動使列適應表格寬度以防止出現水平滾動。	false
striped（顯示條紋）	boolean（布爾型）	設置為true將交替顯示行背景。	false
method（方法）	string（字符串）	請求遠程數據的方法類型。	post
nowrap（截取）	boolean（布爾型）	設置為true，當數據長度超出列寬時將會自動截取。	true
idField（id字段）	string（字符串）	表明該列是一個唯一列。	null
url（超鏈接）	string（字符串）	一個用以從遠程站點請求數據的超鏈接地址。	null
loadMsg（載入時信息）	string（字符串）	當從遠程站點載入數據時，顯示的一條快捷信息。	Processing, please wait …
pagination（分頁）	boolean（布爾型）	設置true將在數據表格底部顯示分頁工具欄。	false
rownumbers（行數）	boolean（布爾型）	設置為true將顯示行數。	false
singleSelect（單選模式）	boolean（布爾型）	設置為true將只允許選擇一行。	false
pageNumber（當前頁碼）	number（數字）	當設置分頁屬性時，初始化分頁碼。	1
pageSize（每頁記錄數）	number（數字）	當設置分頁屬性時，初始化每頁記錄數。	10
pageList（可選擇的每頁記錄數）	array	當設置分頁屬性時，初始化每頁記錄數列表。	[10,20,30,40,50]
queryParams（查詢參數）	object（對象）	當請求遠程數據時，發送的額外參數。	{}
sortName（默認排序）	string（字符串）	當數據表格初始化時以哪一列來排序。	null
sortOrder（排序順序）	string（字符串）	定義排序順序，可以是'asc'或者'desc'（正序或者倒序）。	asc
remoteSort（遠程排序）	boolean（布爾型）	定義是否通過遠程服務器對數據排序。	true
showFooter（顯示行底）	boolean（布爾型）	定義是否顯示行底（如果是做統計表格，這里可以顯示總計等）。	false
rowStyler（行樣式）	function（函數）	返回樣式，如：'background:red'，function有2個參數： index：行索引，從0開始. row：對應於該行記錄的對象。
loadFilter（載入過濾器）	function（函數）	返回用以顯示的已過濾數據，function有一個參數'data'表示原始數據，你可以將原始數據改變為規范的數據格式，該函數必須返回包含 'total'和'rows'屬性的標准數據對象。
editors（編輯模式）	object（對象）	定義當編輯一行時的編輯模式。	predefined editors
view（視圖）	object（對象）	定義數據表格的視圖。	default view

列屬性

數據表格的列是一個對象數組，即這個對象中的元素也是一個數組（js中數組是對象）。 對象數組中的每一個元素都是可配置的對象，每個可配置對象定義一個列。

 

示例代碼:

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
sortable（可排序）	boolean（布爾型）	設置為true允許對該列排序。	undefined
resizable（縮放）	boolean（布爾型）	設置為true允許該列被縮放。	undefined
hidden（隱藏）	boolean（布爾型）	設置為true將隱藏列。	undefined
checkbox（復選框）	boolean（布爾型）	設置為true將顯示復選框。	undefined
formatter（格式化）	function（函數）	格式化單元格函數，有3個參數： value：字段的值。 rowData：行數據。 rowIndex：行索引。	undefined
styler（樣式）	function（函數）	單元格樣式函數，返回樣式字符串裝飾表格如'background:red'，function有3個參數： value：字段值。 rowData：行數據。 rowIndex：行索引。	undefined
sorter（排序器）	function（函數）	T自定義字段排序函數，有2個參數： a：該列的第一個值。 b：該列的第二個值。	undefined
editor（編輯器）	string,object（字符串，對象）	表明編輯類型。如果屬性是字符串類型表示編輯類型，如果是對象則包含2個參數： type：字符串，編輯類型，可選值：text，textarea，checkbox，numberbox，validatebox，datebox，combobox，combotree。 options：對象，對象於編輯類型的編輯器屬性。	undefined

編輯器

使用$.fn.datagrid.defaults.editors重載默認值。

 

每個編輯器都有以下方法：

名稱參數描述

init	container, options	初始化編輯器並返回目標對象。
destroy	target	銷毀編輯器。
getValue	target	獲取編輯框的值。
setValue	target , value	設置編輯框的值。
resize	target , width	調整編輯器

例如，如下代碼將定義一個文本編輯器：

$.extend($.fn.datagrid.defaults.editors, {
    text: {
        init: function(container, options){
            var input = $('<input type="text" class="datagrid-editable-input">').appendTo(container);
            return input;
        },
        getValue: function(target){
            return $(target).val();
        },
        setValue: function(target, value){
            $(target).val(value);
        },
        resize: function(target, width){
            var input = $(target);
            if ($.boxModel == true){
                input.width(width - (input.outerWidth() - input.width()));
            } else {
                input.width(width);
            }
        }
    }
});

數據表格視圖

使用$.fn.datagrid.defaults.view重載默認值。

視圖是一個告訴數據表格如何呈現行記錄的對象，對象必須定義以下方法：

名稱參數描述

render	target, container, frozen	當數據載入時調用。 target: DOM對象，數據網格對象。 container: 行記錄容器。 frozen: 是否呈現固定容器。
renderFooter	target, container, frozen	這是一個可選函數用以展現行底。
renderRow	target, fields, frozen, rowIndex, rowData	這是一個可選函數，它可以被render函數調用。
refreshRow	target, rowIndex	定義如何刷新指定的行。
onBeforeRender	target, rows	在視圖被呈現之前觸發。
onAfterRender	target	在視圖被程序之后觸發。

事件

事件繼承控制面板，以下是數據表格獨有的屬性。

名稱參數描述

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	當用戶雙擊單元格時觸發。
onSortColumn	sort, order	當用戶對列排序時觸發，參數如下： sort：排序字段名稱。 order：排序順序。
onResizeColumn	field, width	當用戶調整列寬時觸發。
onSelect	rowIndex, rowData	當用戶選擇一行是觸發，參數如下： rowIndex：被選擇的行索引，從0開始。 rowData：對應於被選擇行的記錄。
onUnselect	rowIndex, rowData	當用戶取消選擇一行時觸發，參數如下： rowIndex：被取消選擇的行索引，從0開始。 rowData：對應於被取消選擇行的記錄。
onSelectAll	rows	當用戶選擇所有行時觸發。
onUnselectAll	rows	當用戶取消選擇所有行時觸發。
onBeforeEdit	rowIndex, rowData	當用戶開始編輯一行時觸發，參數如下： rowIndex：正在編輯的行索引，從0開始。 rowData：對應於正在編輯的行的記錄。
onAfterEdit	rowIndex, rowData, changes	當用戶編輯完成時觸發，參數如下： rowIndex：正在編輯的行索引，從0開始。 rowData：對應於正在編輯的行的記錄。 changes：被改變的字段內容，對應方式為字段：值。
onCancelEdit	rowIndex, rowData	當用戶取消編輯行時觸發，參數如下： rowIndex：正在編輯的行索引，從0開始。 rowData：對應於正在編輯的行的記錄。
onHeaderContextMenu	e, field	當數據表格的列標題被鼠標右鍵單擊時觸發。
onRowContextMenu	e, rowIndex, rowData	當一行被鼠標右鍵單擊時觸發。

方法

 

名稱參數描述

options	none	返回屬性對象。
getPager	none	返回頁面對象。
getPanel	none	返回控制面板對象。
getColumnFields	frozen	返回列字段，如果設置了frozen屬性為true，將返回固定列的字段名。
getColumnOption	field	返回特定的列屬性。
resize	param	縮放和布局。
load	param	載入並顯示第一頁的記錄，如果傳遞了'param'參數，它將會覆蓋查詢參數屬性的值。
reload	param	重載記錄，跟'load'方法一樣但是重載的是當前頁的記錄而非第一頁。
reloadFooter	footer	重載行底記錄。
loading	none	顯示載入狀態。
loaded	none	隱藏載入狀態。
fitColumns	none	讓列寬自動適應數據表格的寬度。
fixColumnSize	none	固定列尺寸。
fixRowHeight	index	固定特定列的高度。
loadData	data	載入本地數據，舊記錄將被移除。
getData	none	返回已載入數據。
getRows	none	返回當前頁的記錄。
getFooterRows	none	返回行底記錄。
getRowIndex	row	返回指定行的索引，row參數可以是行記錄或者是一個id字段的值。
getSelected	none	返回第一個被選擇的行記錄或null。
getSelections	none	返回所有被選擇的行，當沒有記錄被選擇時，將返回一個空數組。
clearSelections	none	取消所有的已選擇項。
selectAll	none	全選。
unselectAll	none	取消全選。
selectRow	index	選擇一行，行索引從0開始。
selectRecord	idValue	通過傳遞id參數來選擇一行。
unselectRow	index	取消選擇一行。
beginEdit	index	開始編輯一行。
endEdit	index	結束編輯。
cancelEdit	index	取消編輯。
getEditors	index	獲取指定行的編輯器，每個編輯器有如下屬性： actions：編輯器可以做的行為。 target：目標編輯器jQuery對象。 field：字段名。 type：編輯器類型。
getEditor	options	獲取特定的編輯器，options參數有2個屬性： index：行索引。 field:字段名。
refreshRow	index	刷新一行。
validateRow	index	校驗指定的行，如果有效返回true。
updateRow	param	更新指定的行，param參數包含如下屬性： index：要更新的行索引。 row：新的行數據。
appendRow	row	添加一行。
insertRow	param	插入一個新行，param參數包含如下屬性： index：要插入的行索引，如果沒有定義則在最后面添加一個新行。 row：行數據。
deleteRow	index	刪除一行。
getChanges	type	獲取從最后一次提交開始的被修改的所有行，type參數表明修改的類型，可選值：inserted，deleted，updated等 。當沒有傳遞type參數時，返回所有被修改的行。
acceptChanges	none	提交所有修改的數據，提交后的數據將不能再修改或者回滾。
rejectChanges	none	回滾所有被刪除的行。
mergeCells	options	合並單元格，options參數包含如下屬性： index：行索引。 field：字段名。 rowspan：整合單元格要跨的行數。 colspan：整合單元格要跨的列數。
showColumn	field	顯示特定的列。
hideColumn	field	隱藏特定的列。

 

 

創建datagrid

在頁面上添加一個div或table標簽，然后用jquery獲取這個標簽，並初始化一個datagrid。代碼如下：

頁面上的div標簽：

<div id="magazineGrid">
</div>

js代碼：

$('#magazineGrid').datagrid({
    height: 340,
    url: 'url',
    method: 'POST',
    queryParams: { 'id': id },
    idField: '產品ID',
    striped: true,
    fitColumns: true,
    singleSelect: false,
    rownumbers: true,
    pagination: false,
    nowrap: false,
    pageSize: 10,
    pageList: [10, 20, 50, 100, 150, 200],
    showFooter: true,
    columns: [[
        { field: 'ck', checkbox: true },
        { field: '刊名', title: '刊名', width: 180, align: 'left' },
        { field: '類別', title: '類別', width: 150, align: 'left' },
        { field: '月份', title: '月份', width: 100, align: 'left' },
        { field: '期次', title: '期次', width: 100, align: 'left' },
        { field: '價格', title: '價格', width: 100, align: 'right' },
        { field: '訂閱數', title: '訂閱數', width: 100, align: 'right' },
        { field: '庫存數', title: '庫存數', width: 100, align: 'right' },
        { field: '郵寄方式', title: '郵寄方式', width: 80, align: 'left' },
        { field: '數量', title: '數量', width: 80, align: 'left',
            editor: {
                type: 'numberbox',
                options: {
                    min: 0,
                    precision: 0
                }
            }
        }
    ]],
    onBeforeLoad: function (param) {
    },
    onLoadSuccess: function (data) {
        
    },
    onLoadError: function () {
        
    },
    onClickCell: function (rowIndex, field, value) {
        
    }
});

 

ajax請求返回的數據格式

datagrid在創建完成后會根據url請求數據，這是通過ajax來完成的。服務器在完成請求處理后應返回帶有rows屬性的數據，如果用到分頁，還需要有total屬性：

var rst = new { total = iTotalCount, rows = entityList };

說到ajax請求，難免需要在請求的時候傳入一些查詢條件，我通常是在onBeforeLoad事件中添加查詢條件的：

onBeforeLoad: function (param) {
    var bId = $("#txtBId").val();
    var AllSearchKey = $("#txtAllSearchKey").val();
    param.bId = bId;
    param.AllSearchKey = AllSearchKey;
}

 

分頁處理

如果要啟用分頁，在datagrid配置中，首先要加入如下配置：

pagination: true,

這樣一來我們的datagrid底部就會出現一個分頁工具欄。

這個時侯，datagrid在請求數據的時候會自動的添加分頁的信息：

• page：當前請求的頁碼
• rows：每頁要顯示的行數

在服務器端獲取到這兩個參數值，然后通過獲取數據庫中的總數據行數來完成數據處理。

 

關於checkbox列

上面的js代碼創建的datagrid本身已經添加了checkbox列，就是第一列。checkbox列將會自適應寬度。

{ field: 'ck', checkbox: true },

 

關於rownumber列

rownumber列的配置是在全局設置的，如果設置為true則會添加一列來顯示行號。

rownumbers: true

 

行編輯功能的實現

datagrid本身提供了行編輯的功能。只需要兩個步驟：

1. 設置列的editor屬性
2. 手動觸發編輯

第一步，我們需要在column配置中指明editor，editor有兩個屬性，type和options，有效的type字符串有：

text,textarea,checkbox,numberbox,validatebox,datebox,combobox,combotree

options則對應這些控件的具體配置，包括事件等。

editor: {
    type: 'numberbox',
    options: {
        min: 0,
        precision: 0
    }
}

如果不需要特殊的options配置，直接將type字符串賦給editor即可。

editor:'text'

第二步，我們需要監聽datagrid的onRowClick事件，或者onCellClick事件，我更願意監聽onCellClick事件，可以根據點擊不同的字段來進入編輯模式，並設置單元格編輯控件的focus。

onClickCell: function (rowIndex, field, value) {
    beginEditing(rowIndex, field, value)
}

這里調用了beginEditing方法：

var editIndex = undefined;
var beginEditing = function (rowIndex, field, value) {
    if (field != "數量")
        return;

    if (rowIndex != editIndex) {
        if (endEditing()) {
            $('#magazineGrid').datagrid('beginEdit', rowIndex);
            editIndex = rowIndex;

            var ed = $('#magazineGrid').datagrid('getEditor', { index: rowIndex, field: '數量' });
            $(ed.target).focus().bind('blur', function () {
                endEditing();
            });
        } else {
            $('#magazineGrid').datagrid('selectRow', editIndex);
        }
    }
}
var endEditing = function () {
    if (editIndex == undefined) { return true }
    if ($('#magazineGrid').datagrid('validateRow', editIndex)) {
        var ed = $('#magazineGrid').datagrid('getEditor', { index: editIndex, field: '數量' });
        var number = $(ed.target).numberbox('getValue');
        $('#magazineGrid').datagrid('getRows')[editIndex]['數量'] = number;
        $('#magazineGrid').datagrid('endEdit', editIndex);
        $('#magazineGrid').datagrid('selectRow', editIndex);
        editIndex = undefined;
        return true;
    } else {
        return false;
    }
}

 

列格式化輸出 formatter

在列的配種中設置formatter

formatter: function (value, row, index) {
    if (row.user) {
        return row.user.name;
    } else {
        return value;
    }
}

 

使用工具欄

toolbar: [{
    text: 'Add',
    iconCls: 'icon-add',
    handler: function () { alert('add') }
}, {
    text: 'Cut',
    iconCls: 'icon-cut',
    handler: function () { alert('cut') }
}, '-', {
    text: 'Save',
    iconCls: 'icon-save',
    handler: function () { alert('save') }
}],

 

使用CardView效果

cardView效果是這樣的：

cardView的代碼：

var cardview = $.extend({}, $.fn.datagrid.defaults.view, {
    renderRow: function (target, fields, frozen, rowIndex, rowData) {
        var cc = [];
        cc.push('<td colspan=' + fields.length + ' style="padding:10px 5px;border:0;">');
        if (!frozen) {
            var aa = rowData.itemid.split('-');
            var img = 'shirt' + aa[1] + '.gif';
            cc.push('<img src="images/' + img + '" style="width:150px;float:left">');
            cc.push('<div style="float:left;margin-left:20px;">');
            for (var i = 0; i < fields.length; i++) {
                var copts = $(target).datagrid('getColumnOption', fields[i]);
                cc.push('<p><span class="c-label">' + copts.title + ':</span> ' + rowData[fields[i]] + '</p>');
            }
            cc.push('</div>');
        }
        cc.push('</td>');
        return cc.join('');
    }
});
$(function () {
    $('#tt').datagrid({
        view: cardview
    });
});

cardView其實是使用了datagrid的view配置，重寫了其默認的renderRow方法。基於這種實現，我們可以顯示更多樣式的view。