• 前端
• UI组件

导读

本文以本仓库的 Readme.md 为骨架，系统讲解 DataTables——一个为 jQuery 设计的 HTML 表格增强插件——的定位、安装方式与初始化用法。你将学会用一行 JavaScript 为任意 HTML 表格接入排序、分页与搜索过滤能力，并通过配置对象按需开启或关闭功能；同时结合 media/js/jquery.dataTables.js 的源码实现，理解dataTable()与DataTable()两种初始化方式的底层差异、默认选项的源码出处，以及仓库内 examples 示例目录的实战参考价值。

一、仓库定位：这是一个 legacy 仓库

在深入使用之前，需要先明确本仓库的性质。根据 Readme.md 的说明，本仓库是 DataTables 的legacy 仓库（遗留版本仓库），主源码仓库另有其处，本仓库主要承载已构建好的分发产物。从 package.json 可以确认，本仓库当前对应 DataTables1.10.21版本，核心文件为 media/js/jquery.dataTables.js，其文件头标注的版权信息为©2008-2020 SpryMedia Ltd。

同时，DataTables 官方还维护着一系列Dist-*分发仓库，用于向 NPM、NuGet 等包管理生态发布产物；每个分发仓库对应一个核心 JavaScript 文件、一套样式或一个扩展。官方推荐通过 download builder 获取所需文件（包括 NPM、NuGet、CDN 与直接下载），完整安装细节见官方安装手册——本仓库的 package.json、bower.json、composer.json 则展示了各生态下可用的分发形态。

二、DataTables 是什么：为 HTML 表格注入排序、分页与过滤

DataTables 是 jQuery 的一个表格增强插件，它用极小的成本为普通 HTML 表格加入**排序（sorting）、分页（paging）和过滤（filtering）**能力。其官方目标被一句话概括为：

增强 HTML 表格中数据的可访问性（To enhance the accessibility of data in HTML tables）。

为了实现这一目标，DataTables 在设计时明确面向两类用户：

• 开发者：DataTables 提供了大量选项，控制数据应如何获取、显示和被操作，同时提供一套完整的 API 用于访问和操作表格。
• 终端用户：使用 DataTables 界面的人，可以直观、快速地完成排序、过滤、分页与滚动等操作，从表格信息中获取最大价值。

从源码角度看，这份目标与能力描述在 media/js/jquery.dataTables.js 的类注释中得到印证：插件基于**渐进增强（progressive enhancement）**原则，为任意 HTML 表格附加高级交互控件（见 composer.json 的描述字段）。

2.1 版本与依赖前提

本仓库版本 1.10.21（见 package.json 的version字段）。依赖方面：

• jQuery：>=1.7（package.json 的dependencies，bower.json 要求>=1.7.0）。例如 examples/basic_init/zero_configuration.html 中即使用 jQuery 3.5.1 配合 DataTables 演示。
• 核心构建产物：media/js/jquery.dataTables.js与其压缩版media/js/jquery.dataTables.min.js，以及样式文件media/css/jquery.dataTables.css与压缩版（package.json 的files字段列出了发布时随包携带的文件清单）。

三、安装 DataTables

3.1 官方获取途径

获取 DataTables 的主要途径是使用官方 download builder，它允许开发者勾选所需的核心文件、扩展与样式主题，然后生成自定义下载包或 CDN 引用。也可以直接通过DataTables CDN按需引用单个文件。以上两种方式的具体步骤以官方安装文档为准。

3.2 通过 NPM、Bower 与 Composer 安装

如果偏好包管理器，本仓库对应的分发包以datatables.net为名发布在 NPM 与 Bower 上。若要使用 Bootstrap、Foundation 等其他样式库的配套样式，只需在包名上添加对应后缀即可。此外 composer.json 表明 PHP 生态下存在datatables/datatables包，版本同样为 1.10.21。

从 bower.json 可以清楚看到包内实际交付的内容：

{ "name": "datatables", "main": [ "media/js/jquery.dataTables.js", "media/css/jquery.dataTables.css", "media/images/sort_asc.png", "media/images/sort_asc_disabled.png", "media/images/sort_both.png", "media/images/sort_desc.png", "media/images/sort_desc_disabled.png" ], "dependencies": { "jquery": ">=1.7.0" }, "license": "MIT" }

可以看到一个 DataTables 包除了核心 JS 与 CSS 外，还内置了排序状态指示图标（sort_asc.png、sort_desc.png、sort_both.png等，位于 media/images/），这些图片会在列排序时自动显示在表头。

四、快速上手：一行代码初始化表格

4.1 最简初始化

在最简单的情况下，DataTables 只需一行 JavaScript 即可完成初始化：

$('table').dataTable();

其中 jQuery 选择器用来取得要增强的目标表格的引用。由于 DataTables默认开启大部分功能，这行代码执行后，表格立即获得搜索（searching）、排序（ordering）和分页（paging）能力。

这一点可以从两个层面得到验证：

• 示例层面：examples/basic_init/zero_configuration.html 正是"零配置"演示——页面在$(document).ready中仅执行$('#example').DataTable();，就为一张 50 余行的员工表注入了完整的搜索框、可点击排序的表头和分页条。
• 源码层面：media/js/jquery.dataTables.js 中DataTable.defaults的默认选项（详见下文"默认选项"小节）将分页、排序、搜索等特性全部置为开启。

4.2 通过配置对象定制行为

如果需要让 DataTables 执行特定动作，可以在构造器中传入一个配置对象。Readme 给出了关闭分页并开启纵向滚动的示例：

$('table').dataTable( { paginate: false, scrollY: 300 } );

这段代码将禁用分页功能，同时让表格在纵向超出 300 像素时启用滚动。Readme 同时指出，DataTables 全部可用选项的完整列表收录于官方文档。这里需要提醒：配置项名称同时兼容**驼峰式（camelCase）**与1.9 时代遗留的匈牙利命名法（如bPaginate）——源码中_fnCamelToHungarian函数（见 media/js/jquery.dataTables.js 约 2027 行处的调用）负责将现代命名映射为内部旧式名称，因此新旧两种写法都能被正确解析。

4.3 两种初始化方式的源码级差异

不少初学者会困惑dataTable()与DataTable()的区别。查看 media/js/jquery.dataTables.js 末尾的 jQuery 挂载代码（约 15168–15188 行）即可解开疑问：

// jQuery access $.fn.dataTable = DataTable; // Provide access to the host jQuery object (circular reference) DataTable.$ = $; // Legacy aliases $.fn.dataTableSettings = DataTable.settings; $.fn.dataTableExt = DataTable.ext; // With a capital `D` we return a DataTables API instance rather than a // jQuery object $.fn.DataTable = function ( opts ) { return $(this).dataTable( opts ).api(); }; // All properties that are available to $.fn.dataTable should also be // available on $.fn.DataTable $.each( DataTable, function ( prop, val ) { $.fn.DataTable[ prop ] = val; } );

关键结论：

• $().dataTable(opts)：返回经过 jQuery 链式包装的对象，适合在 jQuery 调用链中继续操作 DOM。
• $().DataTable(opts)：内部调用dataTable(opts).api()，返回的是DataTables API 实例，方便直接调用rows()、search()、order()等 API 方法进行数据访问与操作。
• 源码同时把DataTable.settings与DataTable.ext暴露为遗留别名$.fn.dataTableSettings与$.fn.dataTableExt，供老版本插件和代码继续使用。

另外，media/js/jquery.dataTables.js 顶部采用 UMD 包装（约 23–55 行），支持三种加载环境：

• AMD：define(['jquery'], factory)；
• CommonJS：module.exports = function (root, $)，可配合 Node 环境的require('jquery')；
• 浏览器全局：直接调用factory(jQuery, window, document)。

因此同一份文件既能通过<script>标签引入，也能被 RequireJS、webpack 等模块系统加载。

五、默认选项：为什么零配置也能"开箱即用"

DataTables 的默认行为全部集中在 media/js/jquery.dataTables.js 约 9935 行起的DataTable.defaults对象中。以下是源码中可查证的几个关键默认值（注意源码中保留的是内部匈牙利命名，即bPaginate等）：

也就是说，之所以$('table').dataTable()一行即可工作，是因为这些特性在DataTable.defaults中默认开启；而当你传入{ paginate: false }这类配置时，初始化流程会将用户配置与DataTable.defaults合并（源码约 881 行var defaults = DataTable.defaults;处的逻辑），从而覆盖默认行为。

六、仓库内可运行的示例资源

本仓库 examples/ 目录收录了大量可直接在浏览器中打开运行的 HTML 示例，按主题组织为 8 大类，是学习 DataTables 的最佳配套教材：

• examples/basic_init/：基础初始化——零配置、功能开关、排序、多列排序、多表、隐藏列、复杂表头、DOM 定位、弹性宽度、状态保存、数据渲染、滚动等（入口见 examples/basic_init/index.html）。
• examples/advanced_init/：高级初始化——DOM/jQuery 事件、DataTables 事件、列渲染、每页条数、多控件、HTML5data-*属性、默认值设置、行分组、表尾回调等（入口见 examples/advanced_init/index.html）。
• examples/styling/：样式集成——基础样式、Bootstrap 3/4、Foundation、Semantic UI、jQuery UI ThemeRoller、Material Design 与 UIKit 3 预览版（入口见 examples/styling/index.html）。
• examples/data_sources/：数据来源——DOM 数据、Ajax 数据、JavaScript 数组、服务端处理（入口见 examples/data_sources/index.html）。
• examples/api/：API 使用——增行、列过滤、行高亮、子行详情、行选择、表单输入、索引列、动态显隐列、正则搜索等（入口见 examples/api/index.html）。
• examples/ajax/：Ajax 数据源——数组、对象、嵌套对象、正交数据、延迟渲染等，配套测试数据位于 examples/ajax/data/（入口见 examples/ajax/index.html）。
• examples/server_side/：服务端处理——含 PHP 示例脚本 examples/server_side/scripts/server_processing.php、SSP 类 examples/server_side/scripts/ssp.class.php，以及 MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Firebird 等多种数据库建表脚本（见 examples/server_side/scripts/ 目录），此外还覆盖自定义 HTTP 变量、POST 数据、JSONP、流水线分页等高级主题（入口见 examples/server_side/index.html）。
• examples/plug-ins/：插件机制——API 插件方法、排序插件（含/不含类型检测）、范围过滤、实时 DOM 排序（入口见 examples/plug-ins/index.html）。

每个示例页面底部都附有完整的 JavaScript、HTML、CSS 代码标签页，并直接引用 media/js/jquery.dataTables.js 与 media/css/jquery.dataTables.css，适合直接复制改造。

七、文档、支持与许可证

• 文档：DataTables 的完整选项、API 与插件接口文档集中在官方站点；官方站点还介绍了大量可用于进一步增强和定制表格的扩展与插件。
• 支持：官方支持渠道包括 DataTables 官方论坛与商业支持方案。
• 许可证：DataTables 以MIT 许可证发布，允许自由使用、修改和分发，前提是保留版权头——具体而言是 media/js/jquery.dataTables.js 顶部以/*!开头的那段注释块（本仓库同时提供 license.txt）。仓库自身的 package.json、bower.json 与 composer.json 中，license字段也均声明为 MIT。

八、总结

本仓库作为 DataTables 1.10.21 的分发型仓库，其 Readme.md 清晰回答了三个问题：DataTables 是什么（为 jQuery 表格加入排序、分页、过滤的增强插件）、如何安装（download builder、CDN、NPM/Bower 的datatables.net包、Composer 的datatables/datatables包）、如何使用（$('table').dataTable()一行初始化，或传入{ paginate: false, scrollY: 300 }这类配置对象定制行为）。结合 media/js/jquery.dataTables.js 的源码，我们还能进一步掌握dataTable()与DataTable()的返回类型差异、UMD 模块加载方式，以及DataTable.defaults中默认开启特性的确切出处；而 examples/ 目录的 8 大类可运行示例，则是从基础到服务端处理全链路的最佳实战参照。

• 前端
• UI组件