ahooks 的 useAntdTable 实现优雅的表格分页和搜索

1. 为什么需要 useAntdTable？

在管理后台开发中，分页表格 + 搜索表单 的组合出现频率高达 90%。传统的实现方式需要手动处理以下逻辑：

分页参数（current/pageSize）
加载状态（loading）
表单筛选条件同步
防抖请求优化
错误处理

而 useAntdTable 是 ahooks 为 Ant Design 量身定制的 Hook，它可以将原本需要 100 行代码的表格逻辑，压缩到 20 行以内！

2. 核心功能一览

功能	传统实现	useAntdTable	代码量对比
分页管理	✅	✅	-70%
加载状态	✅	✅	-90%
表单筛选联动	✅	✅	-80%
防抖请求	❌	✅	-100%
重置功能	✅	✅	-50%

3. 基础用法：5 分钟快速上手

3.1 安装依赖

bash 复制代码

npm install ahooks antd --save

3.2 最小化示例

jsx 复制代码

import { useAntdTable } from 'ahooks';
import { Table, Form, Input, Button } from 'antd';

const getTableData = ({ current, pageSize }, formData) => {
  return fetch(`/api/data?page=${current}&size=${pageSize}&name=${formData.name}`)
    .then(res => res.json());
};

export default () => {
  const [form] = Form.useForm();
  const { tableProps, search } = useAntdTable(getTableData, { form });

  return (
    <div>
      <Form form={form}>
        <Form.Item name="name">
          <Input placeholder="搜索姓名" />
        </Form.Item>
        <Button onClick={search.submit}>搜索</Button>
      </Form>
      
      <Table
        {...tableProps}
        rowKey="id"
        columns={[{ title: '姓名', dataIndex: 'name' }]}
      />
    </div>
  );
};

关键点解析：

getTableData：数据获取函数，接收分页参数和表单值
tableProps：自动注入分页、加载状态、数据源
search ：提供提交（submit）/重置（reset）方法

4. 核心参数深度解析

4.1 数据获取函数（getTableData）

函数签名：

typescript 复制代码

(params: { current: number; pageSize: number }, formData: any) => 
  Promise<{ total: number; list: any[] }>

参数来源：

参数	来源	示例值
`current`	分页器当前页	1
`pageSize`	分页器每页条数	10
`formData`	表单的筛选条件	`{ name: 'Alice' }`

4.2 返回对象说明

属性	类型	作用
`tableProps`	object	直接传递给 Table 的 Props
`search`	object	包含 `submit`/`reset` 方法
`refresh`	function	强制刷新当前页数据
`loading`	boolean	请求加载状态（可自定义 UI）

5. 进阶技巧：释放完整能力

5.1 服务端排序

jsx 复制代码

const getTableData = ({ current, pageSize, sorter }) => {
  const sortParams = sorter?.field 
    ? `&sort=${sorter.field}&order=${sorter.order}`
    : '';
    
  return fetch(`/api/data?page=${current}&size=${pageSize}${sortParams}`);
};

// 在 Table 中启用排序
<Table
  columns={[
    { title: '年龄', dataIndex: 'age', sorter: true }
  ]}
/>

5.2 自定义分页参数

jsx 复制代码

useAntdTable(getTableData, {
  defaultPageSize: 20, // 默认每页 20 条
  defaultParams: [
    { current: 1, pageSize: 20 }, 
    { status: 'active' } // 初始筛选条件
  ]
});

5.3 防抖优化

jsx 复制代码

useAntdTable(getTableData, {
  debounceInterval: 500 // 输入停止 500ms 后发起请求
});

6. 实战案例：用户管理表格

jsx 复制代码

import { ProTable } from '@ant-design/pro-components';

const UserTable = () => {
  const [form] = Form.useForm();
  const { tableProps, search } = useAntdTable(
    async ({ current, pageSize, sorter }) => {
      const params = {
        page: current,
        size: pageSize,
        sort: sorter?.field,
        order: sorter?.order,
        ...form.getFieldsValue()
      };
      return fetch('/api/users', { params });
    },
    { form, debounceInterval: 300 }
  );

  return (
    <ProTable
      {...tableProps}
      form={form}
      columns={[
        { title: '姓名', dataIndex: 'name', search: true },
        { title: '邮箱', dataIndex: 'email', sorter: true },
        { title: '注册时间', dataIndex: 'createdAt', valueType: 'date' }
      ]}
      rowSelection={{}}
      toolBarRender={() => [
        <Button key="export">导出Excel</Button>
      ]}
    />
  );
};

高级功能整合：

ProTable 增强：集成搜索表单、工具栏
复合排序：多列组合排序
批量操作 ：通过 rowSelection 实现

7. 注意事项与避坑指南

7.1 常见问题

问题	解决方案
数据格式不符	在 `getTableData` 中转换数据
表单重置后数据不更新	检查是否遗漏 `form.reset()`
重复请求	调整 `debounceInterval` 参数
分页器样式错位	检查外层容器是否限制宽度

7.2 性能优化建议

虚拟滚动 ：对大数据量使用 react-virtualized
请求缓存：利用 SWR 或 react-query
分页持久化：将分页状态存入 URL
按需加载 ：使用 @ant-design/pro-table 的轻量模式

8. 总结

通过 useAntdTable，开发者可以：

减少 80% 的样板代码
统一管理分页、加载、筛选状态
轻松实现防抖、排序等高级功能

对于中后台系统的表格场景，useAntdTable + ProTable 的组合可以将开发效率提升 3 倍以上。立即尝试这些最佳实践，让你的表格代码既简洁又强大！

相关资源：