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

简单应用

在下面的例子中,表格左侧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
  • 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来增强下面的原生表格 -->
<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']},
        // 更多数据
    ]
}

列定义和行数据定义的大部分非数据属性都可以在原始表格中的thtr标签上以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
  • true(默认):支持排序;
  • false:不支持排序;
  • 'down':默认使用降序排序;
  • 'up':默认使用升序排序;
如果排序启用时定义此列是否可以排序。
行数据

每行数据的可定义属性如下:

属性名称 合法值 说明
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';
    // 更多的修改...
});