数据表格插件是一个展示大量数据的强力工具。

简单应用

在下面的例子中,表格左侧5列和右侧两列分别固定在两侧,其宽度不受外部容器宽度影响,中间位置的列则在宽度不够时会隐藏超出的部分,隐藏的列可以通过拖拽表头移动到可视区域,也可以使用下方的滚动条来调整隐藏的列显示区域。当向下滚动页面时,如果表头一旦处于不可见的位置时,则表头会调整样式而固定在页面顶端保持一直可见。

<!-- HTML 代码 -->
<table class="table datatable">
  <thead>
    <tr>
      <th>#</th>
      <th>时间</th>
      ...
    </tr>
  </thead>
  <tbody>
    <tr>...</tr>
    <tr>...</tr>
    ...
  </tbody>
</table>


/* JS 代码 */
$('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
  • false (默认)
  • true
是否启用行选中状态维护,启用后将在列首显示多选按钮
checkByClickRow
  • false
  • true (默认)

是否点击行的任意位置来切换选中状态

仅在checkable选项为true时生效

checkedClass 字符串,默认为"active"

行选中时,为表格中的<tr>标签增加的类名由该参数指定

仅在checkable选项为true时生效

storage
  • false
  • true (默认)
是否启用本地存储来增强用户体验。启用该选项之后,表格排序状态及选中的行在用户刷新页面之后仍然会还原为之前的扎状态。
sortable
  • false (默认)
  • true
是否启用表格排序,点击表头能够以该列来为数据排序
fixedHeader
  • false
  • true (默认)
是否固定表格头部,如果启用当页面滚动到下方导致表头不可见时重新定位表头到页面顶部保持可见
fixedHeaderOffset 数字,默认值为0

当标题固定时距离顶部的高度,当页面顶部包含其他固定的内容时需要调整该值

仅在fixedHeaderOffset选项为true时生效

fixedLeftWidth 数字或者表示百分比的字符串,默认值为"30%" 左侧固定的所有列的宽度,可以指定为百分比
fixedRightWidth 数字或者表示百分比的字符串,默认值为"30%" 右侧固定的所有列的宽度,可以指定为百分比
flexHeadDrag
  • false
  • true (默认)
是否能够通告拖拽可变区域的头部来调整可见区域
scrollPos
  • 'in' (默认)
  • 'out'
滚动条位置
rowHover
  • false
  • true (默认)
是否在行上启用鼠标悬停样式
colHover
  • false
  • true (默认)
是否在列上启用鼠标悬停样式,仅当鼠标悬停表头时生效
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" 数据加载完毕后调用
  • event.data 表格数据
ready "ready.zui.datatable" 渲染完毕后调用,可以在此事件中为DOM绑定其他事件
sort "sort.zui.datatable" 表格重新排序之后
  • event.sorter.index 数字,排序所依据的列序号
  • event.sorter.sortUp 排序方向,true为升序,false 为降序
sizeChanged "sizeChanged.zui.datatable" 列宽发生更改时发生
  • event.changes.change 字符串,变化的类型,"fixedLeftWidth" 为左侧所有固定列总宽度发生变化,"fixedRightWidth" 为右侧所有固定列总宽度发生变化,"colWidth" 为单个列宽度发生变化
  • event.changes.oldWidth 数字,发生变化之前的宽度值
  • event.changes.newWidth 数字,新的宽度值
  • event.changes.colIndex 数字,如果是单个列宽发生变化,则该值指示发生变化列的序号
checksChanged "checksChanged.zui.datatable" 当行的选中状态发生变化时发生
  • event.checks.checkedAll 如果为true 标识当前所有行都被选中,反之则表示至少有一行为被选中
  • event.checks.checks 数字数组,包含所有已选中的行的ID
使用启动参数处理事件
$('table.datatable').datatable(
{
    sort: function(event)
    {
        console.log(event);
        // console.log("表格已重新排序!");
        // 处理 sort 事件
        // ...
    }
});
使用jQuery方法绑定事件处理函数
$('table.datatable').datatable().on("sort.zui.datatable", function(event)
{
    console.log(event);
    // console.log("表格已重新排序!");
    // 处理 sort 事件
    // ...
});

数据配置

增强现有表格

直接对一个包含完整头部和数据的普通表格进行增强。DataTable或自动获取所有表头和行上的数据,并配置相关选项。

增强现有的表格能够在DataTable组件不可用时也能够正常显示原表格数据。

在启动选项中初始化数据

通过设置启动选项的data属性来初始化数据。

更新数据

当数据表格所依据的原始数据发生变更时,需要手动调用load方法来更新数据表格。

// 当原始数据发生变更时:
$('table.datatable').datatable('load');