TopJUI前端框架

Appearance

DataGrid（数据表格） ​

扩展自$.fn.iPanel.defaults。使用$.fn.iDatagrid.defaults重写默认值对象。

DataGrid以表格形式展示数据，并提供了丰富的选择、排序、分组和编辑数据的功能支持。DataGrid的设计用于缩短开发时间，并且使开发人员不需要具备特定的知识。它是轻量级的且功能丰富。单元格合并、多列标题、冻结列和页脚只是其中的一小部分功能。

依赖关系 ​

使用案例 ​

从现有的表格元素创建DataGrid，在HTML中定义列、行和数据。

html
<table data-toggle="topjui-datagrid">
    <thead>
        <tr>
            <th data-options="field:'code'">编码</th>
            <th data-options="field:'name'">名称</th>
            <th data-options="field:'price'">价格</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>001</td><td>名称1</td><td>2323</td>
        </tr>
        <tr>
            <td>002</td><td>名称2</td><td>4612</td>
        </tr>
    </tbody>
</table>

通过 <table> 标签创建DataGrid控件。在表格内使用 <th> 标签定义列。

html
<table data-toggle="topjui-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">编码</th>
            <th data-options="field:'name',width:100">名称</th>
            <th data-options="field:'price',width:100,align:'right'">价格</th>
        </tr>
    </thead>
</table>

此外，也允许使用Javascript去创建DataGrid控件。

html
<table id="dg"></table>
javascript
$('#dg').iDatagrid({
    url:'datagrid_data.json',
    columns:[[
        {field:'code',title:'代码',width:100},
        {field:'name',title:'名称',width:100},
        {field:'price',title:'价格',width:100,align:'right'}
    ]]
});

使用一些参数查询数据。

javascript
$('#dg').iDatagrid('load', {
    name: 'topjui',
    address: 'ho'
});

改变的数据保存到服务器之后，刷新当前数据。

javascript
$('#dg').iDatagrid('reload');    // 重新载入当前页面数据

DataGrid属性 ​

该属性扩展自panel(面板)，下面是DataGrid控件添加的属性。

属性名属性值类型描述默认值
columnsarray数据表格列配置对象，详情请查看下面的"列属性"表格说明undefined
frozenColumnsarray同列属性，但是这些列将会被冻结在左侧。undefined
fitColumnsboolean真正的自动展开/收缩列的大小，以适应网格的宽度，防止水平滚动。false
resizeHandlestring调整列的位置，可用的值有：'left','right','both'。在使用'right'的时候用户可以通过拖动右侧边缘的列标题调整列，等等。right
resizeEdgenumber重置列位置，可选值：'left','right','both'. 例如，当选择'right'时，用户可以通过拖动列标题的右边缘来调整列的大小。right
autoRowHeightboolean定义设置行的高度，根据该行的内容。设置为false可以提高负载性能。true
toolbararray,selector顶部工具栏的DataGrid面板。可能的值：1) 一个数组，每个工具属性都和linkbutton一样。2) 选择器指定的工具栏。见下方代码示例。null
stripedboolean是否显示斑马线效果。false
methodstring该方法类型请求远程数据。post
nowrapboolean如果为true，则在同一行中显示数据。设置为true可以提高加载性能。true
idFieldstring指明哪一个字段是标识字段。null
urlstring一个URL从远程站点请求数据。null
dataarray,object数据加载。见下方代码示例。null
loadMsgstring在从远程站点加载数据的时候显示提示消息。Processing, please wait …
emptyMsgstring不存在记录时要显示的消息。false
paginationboolean如果为true，则在DataGrid控件底部显示分页工具栏。false
rownumbersboolean如果为true，则显示一个行号列。false
singleSelectboolean如果为true，则只允许选择一行。false
ctrlSelectboolean在启用多行选择的时候允许使用Ctrl键+鼠标点击的方式进行多选操作。false
checkOnSelectboolean如果为true，当用户点击行的时候该复选框就会被选中或取消选中。如果为false，当用户仅在点击该复选框的时候才会被选中或取消。true
selectOnCheckboolean如果为true，单击复选框将永远选择行。如果为false，选择行将不选中复选框。true
scrollOnSelectboolean如果为true，在选择行的时候将自动定位到行所在的位置。true
pagePositionstring定义分页工具栏的位置。可用的值有：'top','bottom','both'。true
pageNumbernumber在设置分页属性的时候初始化页码。1
pageSizenumber在设置分页属性的时候初始化页面大小。10
pageListarray在设置分页属性的时候初始化页面大小选择列表。[10,20,30,40,50]
queryParamsobject在请求远程数据的时候发送额外的参数。见下方代码示例。{}
sortNamestring定义哪些列可以进行排序。null
sortOrderstring定义列的排序顺序，只能是'asc'或'desc'。asc
multiSortboolean定义是否允许多列排序。false
remoteSortboolean定义从服务器对数据进行排序。true
showHeaderboolean定义是否显示行头。true
showFooterboolean定义是否显示行脚。false
scrollbarSizenumber滚动条的宽度(当滚动条是垂直的时候)或高度(当滚动条是水平的时候)。18
rownumberWidthnumber行号列宽度。30
editorHeightnumber编辑器默认高度。24
rowStylerfunction返回样式如'background:red'。带2个参数的函数：index：该行索引从0开始，row：与此相对应的记录行。见下方代码示例。
loaderfunction定义如何从远程服务器加载数据。返回false可以放弃本次请求动作。该函数接受以下参数：param：参数对象传递给远程服务器。success(data)：当检索数据成功的时候会调用该回调函数。error()：当检索数据失败的时候会调用该回调函数。json loader
loadFilterfunction返回过滤数据显示。该函数带一个参数'data'用来指向源数据（即：获取的数据源，比如Json对象）。您可以改变源数据的标准数据格式。这个函数必须返回包含'total'和'rows'属性的标准数据对象。见下方代码示例。
editorsobject定义在编辑行的时候使用的编辑器。预定义编辑器
viewobject定义DataGrid的视图。默认视图
initCreateboolean是否在页面创建完成后初始化表格对象，默认为true。在多表格加载情况下，建议设置为false，可以提高加载效率。true

代码示例 ​

toolbar属性示例：

在 <div> 标签上定义工具栏：

javascript
$('#dg').iDatagrid({
    toolbar: '#tb'
});
html
<div id="tb">
    <a href="#" data-toggle="topjui-linkbutton"
       data-options="iconCls:'icon-edit',plain:true">编辑</a>
    <a href="#" data-toggle="topjui-linkbutton"
       data-options="iconCls:'icon-help',plain:true">帮助</a>
</div>

通过数组定义工具栏：

javascript
$('#dg').iDatagrid({
    toolbar: [{
        iconCls: 'icon-edit',
        handler: function(){alert('编辑按钮')}
    },'-',{
        iconCls: 'icon-help',
        handler: function(){alert('帮助按钮')}
    }]
});

data属性示例：

javascript
$('#dg').iDatagrid({
    data: [
        {f1:'value11', f2:'value12'},
        {f1:'value21', f2:'value22'}
    ]
});

queryParams属性示例：

javascript
$('#dg').iDatagrid({
    queryParams: {
        name: 'topjui',
        subject: 'datagrid'
    }
});

rowStyler属性示例：

javascript
$('#dg').iDatagrid({
    rowStyler: function(index,row){
        if (row.listprice>80){
            return 'background-color:#6293BB;color:#fff;'; // 返回内联样式
        }
    }
});
javascript
$('#dg').iDatagrid({
    rowStyler: function(index,row){
        if (row.listprice>80){
            // 该函数可以返回预定义的css类和内联样式
            // rowStyle是一个已经定义了的ClassName(类名)。内联样式优先级大于rowStyle中的样式
            return {class:'rowStyle',style:'color:#fff'};
        }
    }
});

loadFilter属性示例：

javascript
// 从Web Service（asp.net、java、php等）输出的JSON对象中移除'd'对象
$('#dg').iDatagrid({
    loadFilter: function(data){
        if (data.d){
            return data.d;
        } else {
            return data;
        }
    }
});

扩展属性 ​

属性名属性值类型描述默认值
parentGridobject[可选] 父表格参数空
childGridobject[可选] 子表格参数空
gridobject[可选] 表格自身参数空

列属性 ​

DataGrid列是一个数组对象，该元素也是一个数组对象。元素数组里面的元素是一个配置对象，它用来定义每一个列字段。

代码示例：

javascript
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}
]]
属性名属性值类型描述默认值
titlestring列标题文本。undefined
fieldstring列字段名称。undefined
widthnumber列的宽度。如果没有定义，宽度将自动扩充以适应其内容。undefined
rowspannumber指明将占用多少行单元格（合并行）。undefined
colspannumber指明将占用多少列单元格（合并列）。undefined
alignstring指明如何对齐列数据。可以使用的值有：'left','right','center'。undefined
halignstring指明如何对齐列标题。可以使用的值有：'left','right','center'。如果没有指定，则按照align属性进行对齐。undefined
sortableboolean如果为true，则允许列使用排序。undefined
orderstring默认排序数序，只能是'asc'或'desc'。undefined
resizableboolean如果为true，允许列改变大小。undefined
fixedboolean如果为true，在"fitColumns"设置为true的时候阻止其自适应宽度。undefined
hiddenboolean如果为true，则隐藏列。undefined
checkboxboolean如果为true，则显示复选框。该复选框列固定宽度。undefined
formatterfunction单元格formatter(格式化器)函数，带3个参数：value：字段值。row：行记录数据。index: 行索引。见下方代码示例。undefined
stylerfunction单元格styler(样式)函数，返回如'background:red'这样的自定义单元格样式字符串。该函数带3个参数：value：字段值。row：行记录数据。index: 行索引。见下方代码示例。undefined
sorterfunction用来做本地排序的自定义字段排序函数，带2个参数：a：第一个字段值。b：第二个字段值。见下方代码示例。undefined
editorstring,object指明编辑类型。当字符串指明编辑类型的时候，对象包含2个属性：type：字符串，该编辑类型可以使用的类型有：text,textarea,checkbox,numberbox,validatebox,datebox,combobox,combotree。options：对象，object, 该编辑器属性对应于编辑类型。undefined

列属性代码示例 ​

formatter属性示例：

javascript
$('#dg').iDatagrid({
    columns:[[
        {field:'userId',title:'User', width:80,
            formatter: function(value,row,index){
                if (row.user){
                    return row.user.name;
                } else {
                    return value;
                }
            }
        }
    ]]
});

styler属性示例：

javascript
$('#dg').iDatagrid({
    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'}
                }
            }
        }
    ]]
});

sorter属性示例：

javascript
$('#dg').iDatagrid({
    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);
                }
            }
        }
    ]]
});

Editor（编辑器） ​

使用$.fn.iDatagrid.defaults.editors重写默认值对象。

每一个编辑器都有下面的动作：

名称参数描述
initcontainer, options初始化编辑器并返回目标对象。
destroytarget如果有必要销毁编辑器。
getValuetarget从编辑器中获取值。
setValuetarget , value向编辑器中写入值。
resizetarget , width如果有必要调整编辑器的大小。

例如，该文本编辑器定义如下：

javascript
$.extend($.fn.iDatagrid.defaults.editors, {
    text: {
        init: function(container, options){
            var input = $('<input type="text" data-toggle="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.iDatagrid.defaults.view重写默认值对象。

该视图是一个对象，将告诉DataGrid如何渲染行。该对象必须定义下列函数：

名称参数描述
rendertarget, container, frozen数据加载时调用。target：DOM对象，DataGrid对象。container：行容器。frozen：指明如何渲染冻结容器。
renderFootertarget, container, frozen这是一个选择函数来渲染行页脚。
renderRowtarget, fields, frozen, index, row这是一个属性功能，将调用render函数。
refreshRowtarget, index定义如何刷新指定的行。
onBeforeRendertarget, rows在视图被呈现之前触发。
onAfterRendertarget在视图被呈现之后触发。

事件 ​

事件继承自panel(面板)，以下是DataGrid新增的事件。

事件名参数描述
onLoadSuccessdata在数据加载成功的时候触发。
onLoadErrornone在载入远程数据产生错误的时候触发。
onBeforeLoadparam在载入请求数据数据之前触发，如果返回false可终止载入数据操作。
onClickRowindex, row在用户点击一行的时候触发，参数包括：index：点击的行的索引值，该索引值从0开始。row：对应于点击行的记录。
onDblClickRowindex, row在用户双击一行的时候触发，参数包括：index：点击的行的索引值，该索引值从0开始。row：对应于点击行的记录。
onClickCellindex, field, value在用户点击一个单元格的时候触发。
onDblClickCellindex, field, value在用户双击一个单元格的时候触发。见下方代码示例。
onBeforeSortColumnsort, order在用户排序一个列之前触发，返回false可以取消排序。
onSortColumnsort, order在用户排序一列的时候触发，参数包括：sort：排序列字段名称。order：排序列的顺序(ASC或DESC)
onResizeColumnfield, width在用户调整列大小的时候触发。
onBeforeSelectindex, row在用户选择一行之前触发，返回false则取消该动作。
onSelectindex, row在用户选择一行的时候触发，参数包括：index：选择的行的索引值，索引从0开始。row：对应于取消选择行的记录。
onBeforeUnselectindex, row在用户取消选择一行之前触发，返回false则取消该动作。
onUnselectindex, row在用户取消选择一行的时候触发，参数包括：index：选择的行的索引值，索引从0开始。row：对应于取消选择行的记录。
onSelectAllrows在用户选择所有行的时候触发。
onUnselectAllrows在用户取消选择所有行的时候触发。
onBeforeCheckindex, row在用户校验一行之前触发，返回false则取消该动作。
onCheckindex, row在用户勾选一行的时候触发，参数包括：index：选中的行索引，索引从0开始。row：对应于所选行的记录。
onBeforeUncheckindex, row在用户取消校验一行之前触发，返回false则取消该动作。
onUncheckindex, row在用户取消勾选一行的时候触发，参数包括：index：选中的行索引，索引从0开始。row：对应于取消勾选行的记录。
onCheckAllrows在用户勾选所有行的时候触发。
onUncheckAllrows在用户取消勾选所有行的时候触发。
onBeforeEditindex, row在用户开始编辑一行的时候触发，参数包括：index：编辑行的索引，索引从0开始。row：对应于编辑行的记录。
onBeginEditindex, row在一行进入编辑模式的时候触发。
onEndEditindex, row, changes在完成编辑但编辑器还没有销毁之前触发。
onAfterEditindex, row, changes在用户完成编辑一行的时候触发，参数包括：index：编辑行的索引，索引从0开始。row：对应于完成编辑的行的记录。changes：更改后的字段(键)/值对。
onCancelEditindex,row在用户取消编辑一行的时候触发，参数包括：index：编辑行的索引，索引从0开始。row：对应于编辑行的记录。
onHeaderContextMenue, field在鼠标右击DataGrid表格头的时候触发。
onRowContextMenue, index, row在鼠标右击一行记录的时候触发。

事件代码示例 ​

onDblClickCell事件示例：

javascript
// 在双击一个单元格的时候开始编辑并生成编辑器，然后定位到编辑器的输入框上
$('#dg').iDatagrid({
    onDblClickCell: function(index,field,value){
        $(this).iDatagrid('beginEdit', index);
        var ed = $(this).iDatagrid('getEditor', {index:index,field:field});
        $(ed.target).focus();
    }
});

方法 ​

方法名参数描述
optionsnone返回属性对象。
getPagernone返回页面对象。
getPanelnone返回面板对象。
getColumnFieldsfrozen返回列字段。如果设置了frozen属性为true，将返回固定列的字段名。见下方代码示例。
getColumnOptionfield返回指定列属性。
resizeparam做调整和布局。
loadparam加载和显示第一页的所有行。如果指定了'param'，它将取代'queryParams'属性。通常可以通过传递一些参数执行一次查询，通过调用这个方法从服务器加载新数据。见下方代码示例。
reloadparam重载行。等同于'load'方法，但是它将保持在当前页。
reloadFooterfooter重载页脚行。见下方代码示例。
loadingnone显示载入状态。
loadednone隐藏载入状态。
fitColumnsnone使列自动展开/收缩到合适的DataGrid宽度。
fixColumnSizefield固定列大小。如果'field'参数未配置，所有列大小将都是固定的。见下方代码示例。
fixRowHeightindex固定指定列高度。如果'index'参数未配置，所有行高度都是固定的。
freezeRowindex冻结指定行，当DataGrid表格向下滚动的时候始终保持被冻结的行显示在顶部。
autoSizeColumnfield自动调整列宽度以适应内容。
loadDatadata加载本地数据，旧的行将被移除。
getDatanone返回加载完毕后的数据。
getRowsnone返回当前页的所有行。
getFooterRowsnone返回页脚行。
getRowIndexrow返回指定行的索引号，该行的参数可以是一行记录或一个ID字段值。
getCheckednone在复选框被选中的时候返回所有行。
getSelectednone返回第一个被选中的行或如果没有选中的行则返回null。
getSelectionsnone返回所有被选中的行，当没有记录被选中的时候将返回一个空数组。
clearSelectionsnone清除所有选择的行。
clearCheckednone清除所有勾选的行。
scrollToindex滚动到指定的行。
gotoPageparam跳转到指定页。见下方代码示例。
highlightRowindex高亮一行。
selectAllnone选择当前页中所有的行。
unselectAllnone取消选择所有当前页中所有的行。
selectRowindex选择一行，行索引从0开始。
selectRecordidValue通过ID值参数选择一行。
unselectRowindex取消选择一行。
checkAllnone勾选当前页中的所有行。
uncheckAllnone取消勾选当前页中的所有行。
checkRowindex勾选一行，行索引从0开始。
uncheckRowindex取消勾选一行，行索引从0开始。
beginEditindex开始编辑行。
endEditindex结束编辑行。
cancelEditindex取消编辑行。
getEditorsindex获取指定行的编辑器。每个编辑器都有以下属性：actions：编辑器可以执行的动作，同编辑器定义。target：目标编辑器的jQuery对象。field：字段名称。type：编辑器类型，比如：'text','combobox','datebox'等。
getEditoroptions获取指定编辑器，options包含2个属性：index：行索引。field：字段名称。见下方代码示例。
refreshRowindex刷新行。
validateRowindex验证指定的行，当验证有效的时候返回true。
updateRowparam更新指定行，参数包含下列属性：index：执行更新操作的行索引。row：更新行的新数据。见下方代码示例。
appendRowrow追加一个新行。新行将被添加到最后的位置。见下方代码示例。
insertRowparam插入一个新行，参数包括一下属性：index：要插入的行索引，如果该索引值未定义，则追加新行。row：行数据。见下方代码示例。
deleteRowindex删除行。
getChangestype从上一次的提交获取改变的所有行。类型参数指明用哪些类型改变的行，可以使用的值有：inserted,deleted,updated等。当类型参数未配置的时候返回所有改变的行。
acceptChangesnone提交所有从加载或者上一次调用acceptChanges函数后更改的数据。
rejectChangesnone回滚所有从创建或者上一次调用acceptChanges函数后更改的数据。
mergeCellsoptions合并单元格，options包含以下属性：index：行索引。field：字段名称。rowspan：合并的行数。colspan：合并的列数。
showColumnfield显示指定的列。
hideColumnfield隐藏指定的列。
sortparam排序datagrid表格。见下方代码示例。

方法代码示例 ​

getColumnFields方法示例：

javascript
var opts = $('#dg').iDatagrid('getColumnFields');               // 获取解冻列
var opts = $('#dg').iDatagrid('getColumnFields', true);       // 获取冻结列

load方法示例：

javascript
$('#dg').iDatagrid('load',{
    code: '01',
    name: 'name01'
});

reloadFooter方法示例：

javascript
// 更新页脚行的值并刷新
var rows = $('#dg').iDatagrid('getFooterRows');
rows[0]['name'] = 'new name';
rows[0]['salary'] = 60000;
$('#dg').iDatagrid('reloadFooter');

// 更新页脚行并载入新数据
$('#dg').iDatagrid('reloadFooter',[
    {name: 'name1', salary: 60000},
    {name: 'name2', salary: 65000}
]);

fixColumnSize方法示例：

javascript
$('#dg').iDatagrid('fixColumnSize', 'name');        // 固定'name'列大小
$('#dg').iDatagrid('fixColumnSize');                    // 固定所有列大小

gotoPage方法示例：

javascript
// 跳转到第3页
$('#dg').iDatagrid('gotoPage', 3);

// 跳转到第3页并执行回调函数
$('#dg').iDatagrid('gotoPage', {
    page: 3,
    callback: function(page){
        console.log(page)
    }
})

getEditor方法示例：

javascript
// 获取日期输入框编辑器并更改它的值
var ed = $('#dg').iDatagrid('getEditor', {index:1,field:'birthday'});
$(ed.target).iDatebox('setValue', '5/4/2012');

updateRow方法示例：

javascript
$('#dg').iDatagrid('updateRow',{
    index: 2,
    row: {
        name: '新名称',
        note: '新消息'
    }
});

appendRow方法示例：

javascript
$('#dg').iDatagrid('appendRow',{
    name: '新名称',
    age: 30,
    note: '新消息'
});

insertRow方法示例：

javascript
// 在第二行的位置插入一个新行
$('#dg').iDatagrid('insertRow',{
    index: 1,	// 索引从0开始
    row: {
        name: '新名称',
        age: 30,
        note: '新消息'
    }
});

sort方法示例：

javascript
$('#dg').iDatagrid('sort', 'itemid');    // 排序一个列
$('#dg').iDatagrid('sort', {	        // 指定了排序顺序的列
    sortName: 'productid',
    sortOrder: 'desc'
});

基于最新稳定版jQuery EasyUI构建的前端框架

Copyright © 2024 TopJUI