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

最近在学习jQuery EasyUI，发现中文的文档好少，部分文档不错但它是鸟语的，为了大家也为了自己学习吧，汉化做一下笔记。

有没有说清楚的，或者翻译不正确的地方还请大家谅解指出。。

由于工作时间原因，每天翻译一点，最后会整理出一套帮助文档发布给大家，一起期待哈。。

还有。。。赞一下了哈~打字很累的。。(*^_^*)

DataGrid

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

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

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

[依赖于]

panel
resizable
linkbutton
pagination

[使用实例]

在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，在table表格里嵌套<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');    // 重新加载当前页的数据

[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 工具条： $('#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> 通过数组定义 ToolBar： $('#dg').datagrid({ toolbar: [{ iconCls: 'icon-edit', handler: function(){alert('edit')} },'-',{ iconCls: 'icon-help', handler: function(){alert('help')} }] });	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	当请求远程数据时，附带发送额外的参数。代码示例： $('#dg').datagrid({ queryParams: { name: 'easyui', subject: 'datagrid' } });	{}
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: 符合记录数的行代码示例： $('#dg').datagrid({ rowStyler: function(index,row){ if (row.listprice>80){ return 'background-color:#6293BB;color:#fff;'; } } });
loader	function	定义如何从远程服务器加载数据，返回“false”可以终止这个请求。这个函数需要以下参数： param: 向远程服务器传递的参数对象。 success(data): 这个回调函数会在检索数据成功后调用。 error(): 这个函数会在检索数据失败时调用。	json loader
loadFilter	function	显示返回过滤后的数据。这个函数带一个参数 'data'，它表示原始数据。你可以将原始数据源更改为标准的数据格式。这个函数必须返回一个包含“total”和“rows”属性的标准数据对象。代码示例： // 从 ASP.NET Web Service Json 输出中删除“d”对象 $('#dg').datagrid({ loadFilter: function(data){ if (data.d){ return data.d; } else { return data; } } });
editors	object	定义编辑行时的编辑器。	predefined editors
view	object	定义DataGrid的View视图。	default view

[列属性]

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

代码示例：

 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	单元格格式化的函数，带有三个参数： 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;'; } } } ]] });	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	显示编辑类型，当字符串指明了编辑类型，对象包含两个属性： 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编辑器中如下定义：

 $.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);
             }
         }
     }
 });

[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	当用户双击单元格时触发。代码示例： // 当双击一个单元格时，赋予Editor编辑器焦点，以开始编辑 $('#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	返回paper页面对象。
getPanel	none	返回panel面板对象、
getColumnFields	frozen	返回列字段。如果冻结设置为true，则冻结列字段返回。代码示例： var opts = $('#dg').datagrid('getColumnFields'); // 获取非冻结列 var opts = $('#dg').datagrid('getColumnFields', true); // 获取冻结列
getColumnOption	field	返回指定列的选项option设置。
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	使列自动展开/收缩以适应网格的宽度。
fixColumnSize	field	固定列的大下，如果‘field’参数没有被分配，则所有列大小都将是固定的。代码示例： $('#dg').datagrid('fixColumnSize', 'name'); // 固定‘name’列的大小 $('#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: 字段名称代码示例： // 获取 DateBox 编辑器，并且更改它的值 var ed = $('#dg').datagrid('getEditor', {index:1,field:'birthday'}); $(ed.target).datebox('setValue', '5/4/2012');
refreshRow	index	刷新行。
validateRow	index	验证指定的行，返回“true”时有效。
updateRow	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	插入一个新行，该参数包含以下属性： index: 要插入新行的下标索引位置，如果没有指定，则在后面拼接新增。 row: 要新增的行数据，代码示例如下： // 在第二行插入新行 $('#dg').datagrid('insertRow',{ index: 1, // index start with 0 row: { name: 'new name', age: 30, note: 'some messages' } });
deleteRow	index	删除一行。
getChanges	type	获取自从上次提交后的产生更改的行。这个类型参数指明哪些类型更改了行，可能的值如下：inserted,deleted,updated,等. 当类型参数没有指定时，返回所有更改的行。
acceptChanges	none	提交所有的更改，从它被加载或者上次 acceptChanges 被调用。
rejectChanges	none	回滚自其创建后所有更改的数据，或者从最近一次 acceptChanges 被调用。
mergeCells	options	合并某个列为一个列，这个选项包含以下属性： index: 行下标 field: 字段名称 rowspan: 要合并的行数 colspan: 要合并的列数
showColumn	field	显示指定的列。
hideColumn	field	隐藏指定的列。

[原创汉化，欢迎转载学习，请注明出处：]

Ｑ空间：http://778078163.qzone.qq.com
博客园：http://www.cnblogs.com/LonelyShadow