jQuery EasyUI API - Grid - DataGrid [原创汉化官方API]

2014-04-02  

DataGrid

　　继承自 $.fn.panel.defaults，覆盖默认值 $.fn.datagrid.defaults.

 

 

 

　　DataGrid控件显示数据以表格的形式提供了丰富的选择，支持排序，组和编辑数据。

 

　　DataGrid控件被设计来减少开发时间和要求开发商没有特定的知识。它是轻量级的和功能丰富的。合并单元格，多列标题，冻结列和页脚是仅有的几个特点。

 

 

 

 

[依赖于]

 

panel

resizable

linkbutton

pagination

 

[使用实例]

在HTML标签中，从现有的元素创建表元素、定义列、行中的数据：

 

复制代码

 1 <table class="easyui-datagrid">  

 2     <thead>  

 3         <tr>  

 4             <th data-options="field:‘code‘">Code</th>  

 5             <th data-options="field:‘name‘">Name</th>  

 6             <th data-options="field:‘price‘">Price</th>  

 7         </tr>  

 8     </thead>  

 9     <tbody>  

10         <tr>  

11             <td>001</td><td>name1</td><td>2323</td>  

12         </tr>  

13         <tr>  

14             <td>002</td><td>name2</td><td>4612</td>  

15         </tr>  

16     </tbody>  

17 </table>  

复制代码

 

 

通过<table>标签创建DataGrid，在table表格里嵌套<th>标签定义。

 

复制代码

 1 <table class="easyui-datagrid" style="width:400px;height:250px"  

 2         data-options="url:‘datagrid_data.json‘,fitColumns:true,singleSelect:true">  

 3     <thead>  

 4         <tr>  

 5             <th data-options="field:‘code‘,width:100">Code</th>  

 6             <th data-options="field:‘name‘,width:100">Name</th>  

 7             <th data-options="field:‘price‘,width:100,align:‘right‘">Price</th>  

 8         </tr>  

 9     </thead>  

10 </table>  

复制代码

 

 

使用Javascript也可以创建DataGrid：

 

1 <table id="dg"></table>  

复制代码

1 $(‘#dg‘).datagrid({   

2     url:‘datagrid_data.json‘,   

3     columns:[[   

4         {field:‘code‘,title:‘Code‘,width:100},   

5         {field:‘name‘,title:‘Name‘,width:100},   

6         {field:‘price‘,title:‘Price‘,width:100,align:‘right‘}   

7     ]]   

8 });  

复制代码

 

 

使用一些参数查询数据：

 

1 $(‘#dg‘).datagrid(‘load‘, {   

2     name: ‘easyui‘,   

3     address: ‘ho‘  

4 });  

 

 

改变数据到服务器后，更新之前的数据：

 

1 $(‘#dg‘).datagrid(‘reload‘);    // 重新加载当前页的数据 

 

 

[DataGrid 属性]

属性继承自 panel 面板，下面是从 panel 新增的属性列表：

 

名称 类型

描述 默认值

columns array DataGrid列的配置对象，更多详细请参见列属性。 undefined

frozenColumns array 相同列的属性，但是这些列会被冻结在左边。 undefined

fitColumns boolean 为“true”则自动 展开/收缩 列的大小，为了自动填充Grid的宽度，防止出现水平滚动条。 false

autoRowHeight boolean 定义是否基于行的内容设置行高，设置“false”可以提高加载性能。 true

toolbar array,selector DataGrid面板顶部的 ToolBar 工具条，可以设置的值如下：

1) 一个数组，每个options项是相同的LinkButton。

2) 一个 selector 选择器 指定 ToolBar 工具条。

使用<div>标签定义 ToolBar 工具条：

 

复制代码

 1 $(‘#dg‘).datagrid({

 2     toolbar: ‘#tb‘

 3 });

 4 <div id="tb">

 5 　　<a href="http://www.mamicode.com/#" 

 6       class="easyui-linkbutton" 

 7       data-options="iconCls:‘icon-edit‘,plain:true"></a>

 8 　　<a href="http://www.mamicode.com/#" 

 9       class="easyui-linkbutton" 

10       data-options="iconCls:‘icon-help‘,plain:true"></a>

11 </div>

复制代码

 

 

通过数组定义 ToolBar：

 

复制代码

1 $(‘#dg‘).datagrid({

2     toolbar: [{

3         iconCls: ‘icon-edit‘,

4         handler: function(){alert(‘edit‘)}

5     },‘-‘,{

6         iconCls: ‘icon-help‘,

7         handler: function(){alert(‘help‘)}

8     }]

9 });

复制代码

null

striped boolean 设置“True”实现各行变色的功能。 false

method string 这个方法需要远程数据类型。 post

nowrap boolean 设置为“True”则将数据显示在一行内，设置为“True”可以提高加载性能。 true

idField string 指定哪些字段是标识字段。 null

url string 一个用于请求远程站点的URL路径。 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 当设置分页的属性时，初始化页面数量。 1

pageSize number 当设置分页属性时，初始化页面大小。 10

pageList array 当设置分页属性时，初始化页面大小选择列表、 [10,20,30,40,50]

queryParams object 当请求远程数据时，附带发送额外的参数。

代码示例：

 

1 $(‘#dg‘).datagrid({

2     queryParams: {

3         name: ‘easyui‘,

4         subject: ‘datagrid‘

5     }

6 });

{}

sortName string 定义哪些列可以被排序。 null

sortOrder string 定义列的排序方式，只能是升序“asc”或降序“desc”。 asc

remoteSort boolean 定义是否接受来自远程服务器的排序数据。 true

showHeader boolean 定义是否显示行的页眉。 true

showFooter boolean 定义是否显示行的页脚。 false

scrollbarSize number 滚动条的款(当是垂直滚动条时) 或者 高(当是水平滚动条的时候) 18

rowStyler function 返回例如 ‘background:red‘ 一样的风格样式，这个方法带两个参数：

rowIndex: 行的下标索引，从0开始

rowData: 符合记录数的行

代码示例：

 

复制代码

1 $(‘#dg‘).datagrid({

2     rowStyler: function(index,row){

3         if (row.listprice>80){

4             return ‘color:#fff;‘;

5         }

6     }

7 });

复制代码

 

loader function

定义如何从远程服务器加载数据，返回“false”可以终止这个请求。

 

这个函数需要以下参数：

param: 向远程服务器传递的参数对象。

success(data): 这个回调函数会在检索数据成功后调用。

error(): 这个函数会在检索数据失败时调用。

 

json loader

loadFilter function

显示返回过滤后的数据。这个函数带一个参数 ‘data‘，它表示原始数据。

 

你可以将原始数据源更改为标准的数据格式。

 

这个函数必须返回一个包含“total”和“rows”属性的标准数据对象。

 

代码示例：

 

复制代码

 1 // 从 ASP.NET Web Service Json 输出中删除“d”对象

 2 $(‘#dg‘).datagrid({

 3     loadFilter: function(data){

 4         if (data.d){

 5             return data.d;

 6         } else {

 7             return data;

 8         }

 9     }

10 });

复制代码

 

editors object 定义编辑行时的编辑器。 predefined editors

view object 定义DataGrid的View视图。 default view

 

 

 

 

 

 

 

[列属性]

DataGrid的列是一个数组对象，它的元素也是一个数组。元素的元素数组是一个配置对象，它定义了每一列的字段。

 

 

 

代码示例：

 

复制代码

 1 columns:[[   

 2     {field:‘itemid‘,title:‘Item ID‘,rowspan:2,width:80,sortable:true},   

 3     {field:‘productid‘,title:‘Product ID‘,rowspan:2,width:80,sortable:true},   

 4     {title:‘Item Details‘,colspan:4}   

 5 ],[   

 6     {field:‘listprice‘,title:‘List Price‘,width:80,align:‘right‘,sortable:true},   

 7     {field:‘unitcost‘,title:‘Unit Cost‘,width:80,align:‘right‘,sortable:true},   

 8     {field:‘attr1‘,title:‘Attribute‘,width:100},   

 9     {field:‘status‘,title:‘Status‘,width:60}   

10 ]]  

复制代码

名称 类型 描述 默认值

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 单元格格式化的函数，带有三个参数：

value: 字段值

rowData: 行数据记录

rowIndex: 行下标

代码示例：

 

复制代码

 1 $(‘#dg‘).datagrid({

 2     columns:[[

 3         {field:‘userId‘,title:‘User‘, width:80,

 4             formatter: function(value,row,index){

 5                 if (row.user){

 6                     return row.user.name;

 7                 } else {

 8                     return value;

 9                 }

10             }

11         }

12     ]]

13 });

复制代码

undefined

styler function 单元格样式函数，返回例如 ‘background:red‘ 一样的用户自定义的样式字符串。这个函数带有三个参数：

value: 字段值

rowData: 行数据记录

rowIndex: 行下标

代码示例：

 

复制代码

 1 $(‘#dg‘).datagrid({

 2     columns:[[

 3         {field:‘listprice‘,title:‘List Price‘, width:80, align:‘right‘,

 4             styler: function(value,row,index){

 5                 if (value < 20){

 6                     return ‘color:red;‘;

 7                 }

 8             }

 9         }

10     ]]

11 });

复制代码

undefined

sorter function 用来做局部排序的自定义字段的排序功能，带有两个参数：

a: 第一个字段值

b: 第二个字段值

代码示例：

 

复制代码

 1 $(‘#dg‘).datagrid({

 2     remoteSort: false,

 3     columns: [[

 4         {field:‘date‘,title:‘Date‘,width:80,sortable:true,align:‘center‘,  

 5             sorter:function(a,b){  

 6                 a = a.split(‘/‘);  

 7                 b = b.split(‘/‘);  

 8                 if (a[2] == b[2]){  

 9                     if (a[0] == b[0]){  

10                         return (a[1]>b[1]?1:-1);  

11                     } else {  

12                         return (a[0]>b[0]?1:-1);  

13                     }  

14                 } else {  

15                     return (a[2]>b[2]?1:-1);  

16                 }  

17             }  

18         }

19     ]]

20 });

复制代码

undefined

editor string,object 显示编辑类型，当字符串指明了编辑类型，对象包含两个属性：

type: string，编辑的类型，可以是的值：text,textarea,checkbox,numberbox,validatebox,datebox,combobox,combotree.

options: object, 对应于编辑类型的编辑器选项。 undefined

 

 

 

 

 

 

 

Editor

重写默认值 $.fn.datagrid.defaults.editors.

 

 

 

每个 editor 编辑器都有以下行为：

 

名称 参数 描述

init container, options 初始化 Editor 编辑器，并返回目标对象。

destroy target 如果有必要则摧毁 Editor 编辑器。

getValue target 从 Editor 编辑器获取数据值。

setValue target , value 设置 Editor 编辑器的数据值。

resize target , width 如果需要则调整 Editor 编辑器。

例如，在Editor编辑器中如下定义：

 

复制代码

 1 $.extend($.fn.datagrid.defaults.editors, {   

 2     text: {   

 3         init: function(container, options){   

 4             var input = $(‘<input type="text" class="datagrid-editable-input">‘).appendTo(container);   

 5             return input;   

 6         },   

 7         getValue: function(target){   

 8             return $(target).val();   

 9         },   

10         setValue: function(target, value){   

11             $(target).val(value);   

12         },   

13         resize: function(target, width){   

14             var input = $(target);   

15             if ($.boxModel == true){   

16                 input.width(width - (input.outerWidth() - input.width()));   

17             } else {   

18                 input.width(width);   

19             }   

20         }   

21     }   

22 });  

复制代码

 

 

 

 

 

[DataGrid View]

重写默认值：$.fn.datagrid.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 视图Render前触发。

onAfterRender target 视图在Render后触发。

[事件]

这个时间继承自 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 当用户双击单元格时触发。

代码示例：

 

复制代码

1 // 当双击一个单元格时，赋予Editor编辑器焦点，以开始编辑

2 $(‘#dg‘).datagrid({

3     onDblClickCell: function(index,field,value){

4         $(this).datagrid(‘beginEdit‘, index);

5         var ed = $(this).datagrid(‘getEditor‘, {index:index,field:field});

6         $(ed.target).focus();

7     }

8 });

复制代码

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 返回paper页面对象。

getPanel none 返回panel面板对象、

getColumnFields frozen 返回列字段。如果冻结设置为true，则冻结列字段返回。

代码示例：

1 var opts = $(‘#dg‘).datagrid(‘getColumnFields‘);    // 获取非冻结列

2 var opts = $(‘#dg‘).datagrid(‘getColumnFields‘, true); // 获取冻结列

getColumnOption field 返回指定列的选项option设置。

resize param 做调整，做布局。

load param

加载并显示在第一页的行，如果‘param’指定了，那么它便会随着QueryParams属性取代。

 

通常通过传递一个参数做一个查询，这个方法可以成为从服务器加载新数据。

 

1 $(‘#dg‘).datagrid(‘load‘,{

2     code: ‘01‘,

3     name: ‘name01‘

4 });

reload param 重新加载行，和“load”方法一样，但是停留在当前页面。

reloadFooter footer 重新加载页脚行，代码示例：

复制代码

 1 // update footer row values and then refresh

 2 var rows = $(‘#dg‘).datagrid(‘getFooterRows‘);

 3 rows[0][‘name‘] = ‘new name‘;

 4 rows[0][‘salary‘] = 60000;

 5 $(‘#dg‘).datagrid(‘reloadFooter‘);

 6 

 7 // update footer rows with new data

 8 $(‘#dg‘).datagrid(‘reloadFooter‘,[

 9     {name: ‘name1‘, salary: 60000},

10     {name: ‘name2‘, salary: 65000}

11 ]);

复制代码

loading none 显示加载状态。

loaded none 隐藏加载状态。

fitColumns none 使列自动 展开/收缩 以适应网格的宽度。

fixColumnSize field 固定列的大下，如果‘field’参数没有被分配，则所有列大小都将是固定的。

代码示例：

 

1 $(‘#dg‘).datagrid(‘fixColumnSize‘, ‘name‘);  // 固定‘name’列的大小

2 $(‘#dg‘).datagrid(‘fixColumnSize‘);  // 固定所有列大小

fixRowHeight index 固定指定的行高，如果“index”参数没有分配，则所有行高都将是固定的。

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 清除所有的选择。

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: 该编辑器可以做的action动作，和编辑器定义一样。

target: 目标编辑器的jQuery对象。

field: 字段名称。

type: 编辑器类型，例如‘text‘,‘combobox‘,‘datebox‘, 等.

getEditor options 获取指定的编辑器，该选项包含两个属性：

index: 行下标索引

field: 字段名称

代码示例：

 

1 // 获取 DateBox 编辑器，并且更改它的值

2 var ed = $(‘#dg‘).datagrid(‘getEditor‘, {index:1,field:‘birthday‘});

3 $(ed.target).datebox(‘setValue‘, ‘5/4/2012‘);

refreshRow index 刷新行。

validateRow index 验证指定的行，返回“true”时有效。

updateRow param 更新指定的行，该参数包含以下属性：

index: 要更新的行下标索引。

row: 新行的数据。

代码示例：

 

复制代码

1 $(‘#dg‘).datagrid(‘updateRow‘,{

2     index: 2,

3     row: {

4         name: ‘new name‘,

5         note: ‘new note message‘

6     }

7 });

复制代码

appendRow row 拼接一个新行，这个新行将会被追加在最后的位置：

1 $(‘#dg‘).datagrid(‘appendRow‘,{

2     name: ‘new name‘,

3     age: 30,

4     note: ‘some messages‘

5 });

insertRow param

插入一个新行，该参数包含以下属性：

index: 要插入新行的下标索引位置，如果没有指定，则在后面拼接新增。

row: 要新增的行数据，

 

代码示例如下：

 

复制代码

1 // 在第二行插入新行

2 $(‘#dg‘).datagrid(‘insertRow‘,{

3     index: 1,    // index start with 0

4     row: {

5         name: ‘new name‘,

6         age: 30,

7         note: ‘some messages‘

8     }

9 });

复制代码

deleteRow index 删除一行。

getChanges type

获取自从上次提交后的产生更改的行。

 

这个类型参数指明哪些类型更改了行，可能的值如下：inserted,deleted,updated,等.

 

当类型参数没有指定时，返回所有更改的行。

 

acceptChanges none 提交所有的更改，从它被加载或者上次 acceptChanges 被调用。

rejectChanges none 回滚自其创建后所有更改的数据，或者从最近一次 acceptChanges 被调用。

mergeCells options 合并某个列为一个列，这个选项包含以下属性：

index: 行下标

field: 字段名称

rowspan: 要合并的行数

colspan: 要合并的列数

showColumn field 显示指定的列。

hideColumn field 隐藏指定的列。

jQuery EasyUI API - Grid - DataGrid [原创汉化官方API]