jQuery DataTables 完整实用教程

DataTables 是基于 jQuery 的专业表格插件 ，实现分页、排序、搜索、筛选、样式美化、树形扩展（你之前学的 treeGrid），后台管理系统高频使用。

一、基础环境 & 引入

1. 依赖顺序（必须严格）

jQuery → DataTables CSS → DataTables JS

<!-- 1. jQuery -->
<script src="https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js"></script>

<!-- 2. DataTables 样式 -->
<link rel="stylesheet" href="https://cdn.datatables.net/1.13.6/css/jquery.dataTables.min.css">

<!-- 3. DataTables 脚本 -->
<script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>

2. 基础 HTML 结构

标准表格，必须包含 <thead>（表头）

<table id="myTable" class="display" style="width:100%">
  <thead>
    <tr>
      <th>ID</th>
      <th>姓名</th>
      <th>手机号</th>
      <th>操作</th>
    </tr>
  </thead>
  <tbody>
    <!-- 数据行（静态/动态渲染） -->
  </tbody>
</table>

---

二、三种初始化方式（按场景选用）

方式1：静态本地数据（data 数组）

适合少量模拟数据、测试

$(function(){
  // 模拟数据
  var tableData = [
    { id: 1, name: "张三", phone: "13800138000" },
    { id: 2, name: "李四", phone: "13900139000" }
  ];

  $('#myTable').DataTable({
    data: tableData,
    // 列配置：绑定字段、表头
    columns: [
      { data: "id", title: "ID" },
      { data: "name", title: "姓名" },
      { data: "phone", title: "手机号" },
      { data: null, title: "操作" } // 无绑定字段，放按钮
    ]
  });
});

方式2：AJAX 异步加载（项目最常用）

后端接口返回 JSON 数据，自动分页/渲染

前端代码

$('#myTable').DataTable({
  // 开启服务端分页（大数据必开）
  serverSide: true,
  // 请求接口
  ajax: {
    url: "/api/getList",
    type: "POST"
  },
  columns: [
    { data: "id" },
    { data: "name" },
    { data: "phone" },
    // 自定义单元格：渲染按钮、HTML
    { 
      data: null,
      render: function(row){
        // row = 当前行所有字段
        return `<button class="edit" data-id="${row.id}">编辑</button>
                <button class="del" data-id="${row.id}">删除</button>`;
      }
    }
  ]
});

后端返回格式（serverSide: true 固定格式）

{
  "draw": 1,
  "recordsTotal": 100,    // 总数据条数
  "recordsFiltered": 100, // 筛选后条数
  "data": [
    {"id":1,"name":"张三","phone":"13800138000"}
  ]
}

方式3：渲染已有 HTML 表格

页面已经写好 <tbody> 行，直接初始化即可

$('#myTable').DataTable();

---

三、核心常用配置（高频参数）

$('#myTable').DataTable({
  // 1. 分页相关
  paging: true,        // 开启分页（默认true）
  pageLength: 10,      // 每页条数
  lengthMenu: [5,10,20,50], // 每页条数选择器

  // 2. 搜索、排序
  searching: true,     // 开启全局搜索
  ordering: true,      // 开启列排序
  order: [[0, "desc"]],// 默认排序：第0列 倒序(desc)/正序(asc)

  // 3. 语言汉化（关键，默认英文）
  language: {
    "sProcessing": "加载中...",
    "sLengthMenu": "每页 _MENU_ 条",
    "sZeroRecords": "暂无数据",
    "sInfo": "当前 _START_ - _END_ 条，共 _TOTAL_ 条",
    "sInfoEmpty": "暂无数据",
    "sSearch": "搜索：",
    "oPaginate": {
      "sFirst": "首页",
      "sPrevious": "上一页",
      "sNext": "下一页",
      "sLast": "末页"
    }
  },

  // 4. 列配置
  columns: [
    { data: "id", width: "80px" }, // 设置列宽
    { data: "name", orderable: false }, // 禁止当前列排序
    { data: "phone", searchable: false } // 禁止当前列参与搜索
  ],

  // 5. 动态树形（结合你之前学的 treeGrid）
  treeGrid: {
    left: 20,
    expandAll: false
  }
});

---

四、columns.render 单元格自定义（重点）

用来拼接HTML、格式化文本、状态转换

1. 状态文字转换

{
  data: "status",
  render: function(val){
    // val = 当前字段值
    return val === 1 ? "<span style='color:green'>正常</span>" 
                     : "<span style='color:red'>禁用</span>";
  }
}

2. 操作列按钮

{
  data: null,
  render: function(row){
    return `<button class="btn-edit" data-id="${row.id}">编辑</button>
            <button class="btn-del" data-id="${row.id}">删除</button>`;
  }
}

---

五、常用 API 方法（表格操作）

先获取表格实例：

var table = $('#myTable').DataTable();

1. 重新加载数据（增删改后刷新表格）

// 本地数据 / 前端分页 刷新
table.draw();

// AJAX 接口 重新请求数据（常用）
table.ajax.reload();

2. 清空表格

table.clear().draw();

3. 销毁表格（重新初始化前使用）

// 彻底销毁实例
table.destroy();

4. 获取当前页数据 / 整表数据

// 当前页数据
var pageData = table.rows().data();

5. 跳转指定页

table.page(2).draw(false); // 跳转到第3页（索引从0开始）

---

六、动态行事件绑定（结合 .on() 事件委托）

表格行/按钮是动态渲染 ，必须用事件委托

// 委托给 table，监听内部 .btn-del 点击
$('#myTable tbody').on('click', '.btn-del', function(){
  // 获取当前行 id
  var id = $(this).data('id');
  
  // 结合 swal 确认框
  Swal.fire({
    title: "确定删除？",
    icon: "warning",
    showCancelButton: true
  }).then(res => {
    if(res.isConfirmed){
      $.post("/api/delete", {id:id}, function(){
        Swal.fire("删除成功","","success");
        table.ajax.reload(); // 刷新表格
      });
    }
  });
});

---

七、搭配扩展：dataTables.treeGrid 树形表格

整合写法（完整可运行）

$('#myTable').DataTable({
  ajax: "/api/getTreeData",
  columns: [
    { defaultContent: "", width: "30px" }, // 树形图标列
    { data: "name", title: "名称" },
    { data: "remark", title: "备注" }
  ],
  // 树形配置
  treeGrid: {
    left: 20,
    expandAll: false
  },
  // 树形表格建议关闭分页
  paging: false
});

---

八、常见坑 & 解决方案

1. 表格样式错乱、列宽异常

   • 给 table 加 style="width:100%"
   • 初始化放在 DOM 加载完成 $(function(){}) 内部

2. AJAX 数据渲染不出来

   • 检查接口返回字段名和 columns.data 一致
   • serverSide: true 时，后端必须返回规定格式（draw/recordsTotal/data）

3. 动态按钮点击无反应

   • 不要直接 $(".btn").click()，改用事件委托 tbody.on()

4. 中文搜索乱码/搜索无效

   • 页面编码设为 <meta charset="UTF-8">
   • 后端接口编码统一 UTF-8

5. 树形表格子节点不显示

   • 后端数据必须包含 children 字段

6. 重复初始化报错

   • 重新渲染前先执行 table.destroy()

---

九、极简总结

1. 核心三要素 ：jQuery + 样式CSS + JS；表格必须带 <thead>
2. 两种模式
   • 前端分页：data: [] 本地数组，简单数据用
   • 服务端分页：serverSide:true + ajax，大数据列表必用
3. 自定义内容 ：靠 columns.render 渲染按钮、状态、HTML
4. 动态元素 ：事件一律用 on() 委托
5. 刷新表格 ：增删改后调用 table.ajax.reload()
6. 树形表格 ：增加 treeGrid 配置，数据带 children