数据表格插件是一个展示大量数据的强力工具。
数据表格插件是一个展示大量数据的强力工具。
在下面的例子中,表格左侧5列和右侧两列分别固定在两侧,其宽度不受外部容器宽度影响,中间位置的列则在宽度不够时会隐藏超出的部分,隐藏的列可以通过拖拽表头移动到可视区域,也可以使用下方的滚动条来调整隐藏的列显示区域。当向下滚动页面时,如果表头一旦处于不可见的位置时,则表头会调整样式而固定在页面顶端保持一直可见。
<!-- HTML 代码 -->
<table class="table datatable">
<thead>
<tr>
<!-- 以下两列左侧固定 -->
<th>#</th>
<th>时间</th>
<!-- 以下三列中间可滚动 -->
<th class="flex-col">事件类型</th>
<th class="flex-col">描述</th>
<th class="flex-col">相关人物</th>
<!-- 以下列右侧固定 -->
<th>评分</th>
...
</tr>
</thead>
<tbody>
<tr>...</tr>
<tr>...</tr>
...
</tbody>
</table>
/* 初始化数据表格 */
$('table.datatable').datatable();
只需要更改一个参数即可启用数据排序功能。DataTable支持对数字、日期或字符串进行升序和降序排序。
/* JS 代码 */
$('table.datatable').datatable({sortable: true});
/* JS 代码 */
$('table.datatable').datatable({checkable: true});
你可以启用所有增强选项。
/* JS 代码 */
$('table.datatable').datatable({checkable: true, sortable: true});
参数 | 可选值 | 说明 |
---|---|---|
checkable |
|
是否启用行选中状态维护,启用后将在列首显示多选按钮 |
checkByClickRow |
|
是否点击行的任意位置来切换选中状态 仅在 |
checkedClass |
字符串,默认为"active" |
行选中时,为表格中的 仅在 |
storage |
|
是否启用本地存储来增强用户体验。启用该选项之后,表格排序状态及选中的行在用户刷新页面之后仍然会还原为之前的扎状态。 |
sortable |
|
是否启用表格排序,点击表头能够以该列来为数据排序 |
fixedHeader |
|
是否固定表格头部,如果启用当页面滚动到下方导致表头不可见时重新定位表头到页面顶部保持可见 |
fixedHeaderOffset |
数字,默认值为0 |
当标题固定时距离顶部的高度,当页面顶部包含其他固定的内容时需要调整该值 仅在 |
fixedLeftWidth |
数字或者表示百分比的字符串,默认值为"30%" |
左侧固定的所有列的宽度,可以指定为百分比 |
fixedRightWidth |
数字或者表示百分比的字符串,默认值为"30%" |
右侧固定的所有列的宽度,可以指定为百分比 |
flexHeadDrag |
|
是否能够通告拖拽可变区域的头部来调整可见区域 |
scrollPos |
|
滚动条位置 |
rowHover |
|
是否在行上启用鼠标悬停样式 |
colHover |
|
是否在列上启用鼠标悬停样式,仅当鼠标悬停表头时生效 |
minColWidth |
数字,默认为20 |
列的最小宽度 |
minFixedLeftWidth |
数字,默认为200 |
左侧所有固定列的最小宽度 |
minFixedRightWidth |
数字,默认为200 |
右侧所有固定列的最小宽度 |
minFlexAreaWidth |
数字,默认为200 |
中间可变区域最小宽度 |
/* JS 代码 */
$('table.datatable').datatable(
{
checkable: true,
sortable: true,
checkedClass: "checked",
minFixedLeftWidth: 300
// 更多参数...
});
启动参数也可以直接使用data-*
属性写在要增强的HTML标签上。
Datatable中的事件既可以使用jQuery原生方法来绑定,也可以写在启动参数中。
事件名称 | jQuery事件名称 | 说明 | 事件参数 |
---|---|---|---|
afterLoad |
"afterLoad.zui.datatable" |
数据加载完毕后调用 |
|
ready |
"ready.zui.datatable" |
渲染完毕后调用,可以在此事件中为DOM绑定其他事件 | 无 |
sort |
"sort.zui.datatable" |
表格重新排序之后 |
|
sizeChanged |
"sizeChanged.zui.datatable" |
列宽发生更改时发生 |
|
checksChanged |
"checksChanged.zui.datatable" |
当行的选中状态发生变化时发生 |
|
$('table.datatable').datatable(
{
sort: function(event)
{
console.log(event);
// console.log("表格已重新排序!");
// 处理 sort 事件
// ...
}
});
$('table.datatable').datatable().on("sort.zui.datatable", function(event)
{
console.log(event);
// console.log("表格已重新排序!");
// 处理 sort 事件
// ...
});
直接对一个包含完整头部和数据的普通表格进行增强。DataTable或自动获取所有表头和行上的数据,并配置相关选项。
<!-- 使用Datatable来增强下面的原生表格 -->
<table class="table datatable">
<!-- 定义表头 -->
<thead>
<tr>
<th data-type="number" data-width="80">#</th>
<th data-type="date">时间</th>
<th data-col-class="text-primary">名称</th>
...
</tr>
</thead>
<!-- 定义表格数据,每一个tr对应一个数据,不支持跨行内容 -->
<tbody>
<tr>...</tr>
<tr>...</tr>
...
</tbody>
</table>
/* 初始化数据表格 */
$('table.datatable').datatable(options);
使用增强现有表格的方式能够在DataTable组件不可用时也能够正常显示原表格数据。
通过设置启动选项的data
属性来初始化数据。
<!-- 使用一个div来显示数据表格 -->
<div class="datatable" data-checkable="true" data-sortable="true"></div></code>
/* 使用启动参数选项来初始化数据 */
$('table.datatable').datatable({
data: {
cols: [
{width: 80, text: '#', type: 'number', flex: false, colClass: 'text-center'},
{width: 160, text: '时间', type: 'date', flex: false, sort: 'down'},
{width: 80, text: '名称', type: 'string', flex: true, colClass: ''}
],
rows: [
{checked: false, data: [1, '2016-01-18 11:05:15', '名称示例1']},
{checked: false, data: [2, '2016-01-20 12:06:16', '名称示例2']},
// 更多数据
]
},
// 其他启动参数选项
});
一个完整的数据包含列定义和行数据。类定义在javascript代码中为一个数组,在DOM中为thead
中的tr
标签。行数据在javascript中为一个数组,在DOM中为tbody
中的td
标签。
{
// 列定义
cols: [
{width: 80, text: '#', type: 'number', flex: false, colClass: 'text-center'},
{width: 160, text: '时间', type: 'date', flex: false, sort: 'down'},
{width: 80, text: '名称', type: 'string', flex: true, colClass: ''}
],
// 行数据
rows: [
{checked: false, data: [1, '2016-01-18 11:05:15', '名称示例1']},
{checked: false, data: [2, '2016-01-20 12:06:16', '名称示例2']},
// 更多数据
]
}
列定义和行数据定义的大部分非数据属性都可以在原始表格中的th
和tr
标签上以data-*
属性的形式定义。
每列的可定义属性如下:
属性名称 | 合法值 | 说明 |
---|---|---|
text |
字符串 | 定义此列在界面上显示的名称。 |
width |
80 | '80px' | '80%' | 'auto' (默认) |
定义此列的宽度。 |
flex |
true | false (默认) |
定义此列在数据表格中显示在为水平可滚动的区域,在此列之前的没有定义flex=true 的列则固定在左侧,在此列之后的没有定义flex=true 的列会固定在右侧。必须为连续的多列的flex 属性定义为true 。在DOM中可以为th 标签增加CLASScol-flex 实现,等同于flex=true 。 |
cssClass |
字符串 | 定义数据表格中此列的附加的CSS CLASS值。 |
type |
string (默认) | number | date |
定义此列数据的类型,目前支持字符串、数字和日期。 |
sort |
|
如果排序启用时定义此列是否可以排序。 |
每行数据的可定义属性如下:
属性名称 | 合法值 | 说明 |
---|---|---|
checked |
true | false (默认) |
此行数据在开始时是否为选中状态。 |
data |
数组 | 依次表示此行中每列对应的数据。 |
当数据表格所依据的原始数据或原始表格发生变更时,需要手动调用load()
方法来更新数据表格。load(data)
方法允许增加一个参数来使用需要更新的数据。
data
参数可以为一个回调函数,此回调函数的第一个参数为原始数据,可以直接在回调函数中修改原始数据。
// 更改原始表格数据内容
$('table.datatable-origin').find('td.data-for-change').text('更新此单元格');
// 当原始数据发生变更时:
$('table.datatable').datatable('load');
// 使用data参数更新数据:
$('table.datatable').datatable('load', {
cols: [
{width: 80, text: '#', type: 'number', flex: false, colClass: 'text-center'},
{width: 160, text: '时间', type: 'date', flex: false, sort: 'down'},
{width: 80, text: '名称', type: 'string', flex: true, colClass: ''}
],
rows: [
{checked: false, data: [1, '2016-01-18 11:09:36', '新的名称示例1']},
{checked: false, data: [2, '2016-01-22 12:06:16', '新的名称示例2']},
// 更多数据
]}
});
// 使用data参数可以使用一个回调函数来修改之前的数据:
$('table.datatable').datatable('load', function(data) {
// 修改第1行的第3列数据值为'新的名称示例1'
data.rows[0].data[2] = '新的名称示例1';
// 更多的修改...
});