从 1.10+ 升级到 DataTables 2

DataTables 2 是一个重大版本,相比 1.x 系列,做出许多更改、增强和改进。此外,还删除或更新了一些项,并将这些项突出显示在此文档中。

这是详细介绍 DataTables 2 发布的多篇相关文档之一

对于像 DataTables 这样的库,向后兼容性非常重要,因此在确保尽可能减少 v2 中的重大更改方面花费了大量功夫,但这还是出现了一些,如下所述。

请注意,这不是所有次要更改的详尽列表。要查看完整列表,请 参阅发行说明

更新

文件名

如果您正在通过 script 标记直接加载 DataTables,请注意,DataTables 核心文件的名称已从 jquery.dataTables.js 更改为 dataTables.js。DataTables 默认 CSS 文件也已更新,以便与样式集成文件在命名上保持一致,现在称为 dataTables.dataTables.css

CSS
JS

如果您正在使用 下载程序 来创建合并文件、下载包或使用 NPM/Yarn,则无需担心这个问题。系统会自动处理所有这些内容。仅当您引用 jquery.dataTables.js 时,才需要更新您的 include。

dom 属性

此属性在 DataTables 1.x 中用于在表格周围放置控制和信息元素。它很灵活,但也很难使用,尤其是在与 Bootstrap 等样式库配合使用时,通常会出现难以操作的非常长的字符串。

DataTables 2 引入新的 layout 选项,以便以与样式无关的方式更轻松地处理布局定位。此新属性有效地使 dom 变得冗余,因为这两个选项不能同时使用。但是,dom 是 DataTables 中使用最广泛的参数之一,所以我不希望完全抛弃它。

dom 仍在 DataTables 2 中可用(可能会在 v3 中将其删除!),但 DataTables 的默认 CSS 已针对 layout 进行了更新,不包含 dom 的样式。如果您需要继续使用 dom,您可能需要添加一些 CSS 来根据您的需要定位元素。但是,强烈建议您更新为使用 layout

类名

DataTables 用于添加到表格的元素的类名经过更新,更具一致性并且合理(不同于之前的版本!)。DataTables 1.x 的类名是随着时间的推移而积累的,并且有些杂乱无章。它们现在的命名方式更加一致。它们将以 dt- 开头,以表明它们是针对 DataTables 的。

如果您一直使用旧 DataTables 类名自定义样式,那么您需要为新名称更新您的 CSS。

除了更新类名之外,DataTables 用于存储这些类名的对象结构也经过更新,变得更容易管理。此对象结构由 DataTables 的各种样式集成使用,现在还被视为公共 API 的一部分,让您在需要时轻松更改类名。

您可以找到 此处的数据表使用的默认类名。要自定义,通过 DataTables.ext.classes 访问。

延迟呈现

DataTables 早已具有通过其 deferRender 选项延迟创建表格正文的 DOM 元素直至需要显示它们的能力。这会对性能产生重大影响,尤其是在使用 Ajax 加载的数据时,因为这意味着 DataTables 无需在将 DOM 节点用于当前显示的页面之前创建它们。出于此原因,deferRender 默认值已更改为在 DataTables 2 中启用(true)。

这会影响假定表格正文节点已创建的代码。如果您通过 API 对表格执行 DOM 操作,您可能必须更新代码来实现这一点。可以通过在 DataTables 的初始化选项中添加 deferRender: false 来恢复 v1 行为。

使用空字符串进行 Ajax 加载

如果提供 ajax 选项(或用作对象时的 ajax.url)作为空字符串,则已对其进行更新以不进行请求。以前会调用文稿的 URL。如果您需要那种行为,请使用 ajax: window.location.pathname

明确的标签/输入

现在搜索和页面长度菜单将尽可能使用明确的 label / input|select 对(即输入位于字符串的开头或结尾)。这样做是为了提高可访问性,特别是对于不总是支持之前使用的隐式对的屏幕阅读器。

language.searchlanguage.lengthMenu 是控制此行为的字符串。如果任一输入元素位于字符串的开头或结尾,将使用明确的链接。如果它位于字符串的中间,将使用隐式链接。

因此,language.lengthMenu 的默认值已从 Show _MENU_ entries 更新为 _MENU_ _ENTRIES_ per page

稳定排序

DataTables 中的排序现已 100% 确定。以前,行序可能会取决于先前对表格应用的排序方式(仅当行具有匹配的排序数据时才明显)。现在,数据序会在每次执行排序操作之前重置为最初加载的顺序,以解决此问题。

排序顺序

在 v1 中,通过单击标题元素对列进行排序时,只能在升序和降序排序之间进行切换(可通过 columns.orderSequence 选项控制)。DataTables 2 为此参数引入了一个新选项,即表示没有排序的空字符串值。现在,默认值已更新为使用此选项,且在单击表头单元格时应用的排序顺序现为

  • 升序
  • 降序
  • 无序

单击列标题时,它将无限期地重复该顺序。与以前一样,可以使用 columns.orderSequence 选项进行控制,如果您希望恢复默认 DataTables 1.x 行为,则可以通过设置默认值来实现

DataTable.defaults.column.orderSequence = ['asc', 'desc'];

示例

本网站上的示例 已全部更新,以便能够使用我们支持的任何样式库来设置主题。这通过新的 layout 选项得以实现,该选项允许添加按钮和搜索窗格等功能,而无需特定样式的 dom 字符串。

所有示例还具有在有或没有 jQuery(默认情况下没有)的情况下显示和运行初始化的功能,并且对于支持它的主题,还可以启用深色或浅色模式。

最后,所有示例都已通过 Prettier(实际上,特别是 Prettier More)进行格式化,以提供一致的代码样式。

文档

参考文档 中的代码片段已更新,重点关注非 jQuery 初始化。具体来说,现在通过全局 DataTable 对象访问 DataTables - 例如,之前的示例可能是

$('#myTable').DataTable({
    scrollX: true
});

现在将是

new DataTable('#myTable', {
    scrollX: true
});

两种形式仍然有效!此更改主要是由于 ES 模块的使用越来越多,其中无需导入 jQuery 即可导入 DataTable 对象。

已移除

旧版 API

DataTables 用于扩展其从 $().dataTable() 返回的 jQuery 对象,使用面向 DataTables 的特定方法,例如 fnDrawfnGetData 等(它们都具有 fn 前缀)。当 DataTables 1.10 引入一个全新的可链式 API 时,该 API 已成为旧版且不受支持。DataTables 2 完全删除了旧版 API。如果您正在使用任何旧版的 fn* 方法,则需要更新它们。

deferLoading 选项

此选项在 DataTables 1.x 中可用,用于阻止 DataTables 在其初始启动时替换 HTML 表格的内容。它最初添加到 DataTables 中,以便允许搜索引擎在无需执行 JavaScript 的情况下抓取表格的数据。由于所有搜索引擎都可以执行 JavaScript 以加载 Ajax 数据,因此该问题已经停止存在。由于它给 DataTables 的代码路径增加了大量的复杂性和间接性,因此已将它删除。

pagingTag 选项

此功能在后期的 1.x 版本中已存在,旨在帮助改善无障碍性。最初,DataTables 使用 a 标签来显示分页按钮,但对于无障碍性而言,button 显然是首选。pagingTag 在 1.x 版本中可用,允许使用按钮,而无需更改默认设置。DataTables 2 抓住了机会,将分页按钮更新为 button 元素,因此此选项不再相关。

stripeClasses 选项

DataTables 1.x 将 oddeven 类添加到表格中的每一行,以便实现表格的条带式样式。由于 CSS 的 :nth-child 选择器支持相同的功能,此功能早已变得冗余。此选项已被删除,而表格的条带样式现在仅通过 CSS 完成。

在搜索选项中的 escapeRegex 选项

自 1.10 版本以来,此属性一直没有记录,但出于传统原因,此属性一直存在。使用 DataTables.SearchOptions 对象的 regex 选项来控制是否将字符串视为正则表达式字符串。

concat() 方法

这相当简单地被破坏了,其行为与文档中所述的不符。结果,我决定将其删除,因为它不可能得到任何使用,并且必须向 DataTables 添加额外代码以进行修复。

error 事件

不幸的是,旧 error 事件触发了 window.onerror DOM0 捕获所有错误操作,只是因为其命名。这是不可取的,因此该属性已更名为 dt-error。它在行为上仍然相同,如果您确实希望触发 window.onerror,请设置 DataTable.ext.errMode = 'throw';