Refine v5 useTable 实战指南用 Ant Design Table 快速构建支持分页、排序与筛选的后台列表页【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineuseTable是 Refine v5 中面向 Ant Design 的表格 Hook它返回与 Ant DesignTable示例为实战主线结合 packages/antd/src/hooks/table/useTable/useTable.ts 源码与 完整 Hook 文档讲清楚它的用法、配置项、返回值以及常见问题的解法读完即可在真实 React 管理后台中落地一套完整的列表页。为什么选择 useTable在 Refine v5 中useTable让你不需要为排序、筛选和分页做任何额外操作就能拿到与 Ant DesignTable组件兼容的全部属性。它的核心定位可以从源码中的注释得到印证By using useTable, you are able to get properties that are compatible with Ant DesignTablecomponent. All features such as sorting, filtering and pagination comes as out of box.从 useTable.ts 的实现来看它本身是refinedev/core中useTable的扩展内部先调用核心层的useTableCore完成数据请求与状态管理再通过mapAntdSorterToCrudSorting、mapAntdFilterToCrudFilter把 Ant Design 的表格交互翻译成 Refine 的CrudSorting/CrudFilters。而数据获取这一层底层走的是useListHook也就是说表格数据本质上是一次getList数据提供者调用。useTable完整可用性由单元测试覆盖见 useTable.spec.tsx测试用例覆盖了默认渲染、自定义分页初始值、自定义资源、syncWithLocation、setFilters手动设置筛选、defaultBehavior: replace、分页模式client/server/off、从 URL 参数回填搜索表单等场景可作为理解其行为边界的权威参考。快速上手最小可用列表页以示例项目 examples/table-antd-use-table 为例其数据源为https://api.fake-rest.refine.dev资源为posts见 App.tsx。一个最小可用的useTable列表页大致如下import { List, useTable } from refinedev/antd; import { Table } from antd; export const PostList () { const { tableProps } useTableIPost(); return ( List Table {...tableProps} rowKeyid Table.Column dataIndexid titleID / Table.Column dataIndextitle titleTitle / /Table /List ); };这里有几个要点tableProps展开后自动携带dataSource、loading、onChange、pagination、scroll: { x: true }等Table需要的属性无需手动接线默认情况下useTable会从当前路由推断resource示例中/posts路由对应posts资源无需显式声明rowKeyid是 Ant DesignTable渲染所必需的通常由使用方提供。分页服务端分页与三种模式分页能力由tableProps.pagination开箱即用地提供。从 useTable.ts 源码可以看到antdPagination()会生成完整的TablePaginationConfig包含current当前页、pageSize、total来自data?.total、以及响应式位置小屏居底居中、大屏居右下。更关键的是它会通过createLinkForSyncWithLocation为页码生成真实链接而非纯状态切换并覆盖Table默认的pagination.itemRender。覆盖分页配置如果你想调整Table的分页展示正确的姿势是把tableProps.pagination展开后再覆盖const { tableProps } useTableIPost(); Table {...tableProps} rowKeyid pagination{{ ...tableProps.pagination, position: [bottomCenter], size: small, }} {/* columns */} /Table分页模式pagination.modepagination.mode可选server默认、client、offserver默认模式服务端分页请求携带currentPage与pageSizeclient客户端分页一次性拉取全部记录后在浏览器端分页off禁用分页拉取所有记录此时tableProps.pagination为false源码中isPaginationEnabled为false时antdPagination()直接返回false。useTable({ pagination: { mode: client, }, });对应测试可见 useTable.spec.tsxclient/server模式返回{ pageSize: 10, current: 1 }而off模式下tableProps.pagination为假值。初始分页值useTable({ pagination: { currentPage: 2, // 默认 1 pageSize: 20, // 默认 10 }, });排序列级 sorter 与服务端排序要给列开启排序只需给对应的Table.Column加上sorter属性useTable会自动把 Ant Design 的排序状态映射为CrudSorting并随请求发送给服务端Table.Column dataIndexid titleID sorter /有几个值得注意的细节请求中使用的字段名优先取Column的key没有key时回退到dataIndex因此当dataIndex与排序字段名不一致时可以用key指定多列排序时sorter需要传入{ multiple: 1 }、{ multiple: 2 }等值来声明优先级。示例 list.tsx 中content列为multiple: 1、title列为multiple: 2排序状态同样支持通过syncWithLocation同步到 URL。初始排序与永久排序sorters.initial用于设置初始排序它会被用户的后续操作清除如果需要不可修改的固定排序使用sorters.permanentuseTable({ sorters: { initial: [{ field: name, order: asc }], // permanent: [{ field: name, order: asc }], }, });sorters.mode可设为off或server默认。设为off时排序值不发送给服务端可与 Ant DesignTable的客户端排序如sorter{(a, b) a.id - b.id}配合使用适合数据量小的场景。筛选FilterDropdown 与列级筛选列级筛选依赖Table.Column的filterDropdown属性把筛选表单放入 Refine 提供的FilterDropdown组件中并将函数入参透传给该组件Table.Column dataIndexstatus titleStatus render{(value: string) TagField value{value} /} filterDropdown{(props) ( FilterDropdown {...props} Radio.Group Radio valuepublishedPublished/Radio Radio valuedraftDraft/Radio Radio valuerejectedRejected/Radio /Radio.Group /FilterDropdown )} /在 list.tsx 中可以同时看到字符串筛选Radio.Group、文本包含筛选Input和关联数据多选筛选Select modemultiple三种形态其中关联筛选通过mapValue把选项值转换为数字后再交给FilterDropdown。初始筛选、默认值与 helper 函数设置了filters.initial时必须配合getDefaultSortOrder/defaultFilteredValue让表格列状态与 Hook 状态同步const { tableProps, sorters, filters } useTable({ sorters: { initial: [{ field: title, order: asc }], }, filters: { initial: [{ field: status, operator: eq, value: published }], }, }); Table.Column dataIndextitle titleTitle defaultSortOrder{getDefaultSortOrder(title, sorters)} /; Table.Column dataIndexstatus titleStatus defaultFilteredValue{getDefaultFilter(status, filters)} filterDropdown{(props) ( FilterDropdown {...props}{/* ... */}/FilterDropdown )} /;getDefaultSortOrder(field, sorters)与getDefaultFilter(field, filters, operator?)是refinedev/antd导出的工具函数用于从当前sorters/filters状态中取出指定字段的默认值示例 list.tsx 一次性配置了三个初始筛选title包含空串、status等于draft、category.id属于[1, 2]和一个初始排序title升序并全部回填到列上是完整的参考实现。筛选行为与永久筛选filters.initial会被后续操作清除filters.permanent则恒定生效。filters.defaultBehavior控制setFilters时的合并策略默认merge相同字段替换、不同字段追加可改为replace整体替换useTable({ filters: { defaultBehavior: replace, }, });对应测试 useTable.spec.tsx 验证了replace模式下新筛选会完全覆盖旧筛选。filters.mode与sorters.mode类似可设为off关闭服务端筛选配合Table.Column的filtersonFilter做纯客户端筛选。搜索表单onSearch 与 searchFormPropsuseTable还额外提供了onSearch配置与searchFormProps返回值用来构造独立的搜索表单。onSearch接收表单提交值并返回CrudFilters或PromiseCrudFilters提交后自动把页码重置为 1见 useTable.ts 中onFinish的实现import { List, useTable, SaveButton } from refinedev/antd; import { Table, Form, Input } from antd; interface IPost { id: number; title: string; } interface ISearch { title: string; } const PostList () { const { searchFormProps, tableProps } useTableIPost, HttpError, ISearch({ onSearch: (values) [ { field: title, operator: contains, value: values.title, }, ], }); return ( List Form {...searchFormProps} layoutinline Form.Item nametitle Input placeholderSearch by title / /Form.Item SaveButton onClick{searchFormProps.form?.submit} / /Form Table {...tableProps} rowKeyid Table.Column dataIndexid titleID / Table.Column titleTitle dataIndextitle / /Table /List ); };searchFormProps展开后即 Ant DesignForm的 props其onFinish已被useTable接管配合syncWithLocation时URL 参数中的筛选值会自动回填到表单字段useTable.ts 中通过注册表单字段与filters的匹配完成回填测试见 useTable.spec.tsx。URL 状态同步syncWithLocationsyncWithLocation是后台管理场景的高频需求开启后分页、排序、筛选状态会编码进 URL 查询参数URL 变化时表格状态自动跟随从而支持分享、收藏与刷新后状态保持。可以在 Hook 级开启useTable({ syncWithLocation: true, });也可以在Refine组件上全局开启示例 App.tsx 即使用全局配置options.syncWithLocation: true。此时antdPagination()生成的页码链接会携带完整的pagination、sorters、filters状态实现真正的可分享的表格视图。数据请求与运行时配置由于底层使用useList即 React Query 的useQueryuseTable透传了一系列数据请求与实时能力useTable({ resource: categories, // 显式指定资源默认从路由推断 dataProviderName: second-data-provider, // 多数据提供者时选择目标 queryOptions: { retry: 3 }, // 透传给 useQuery meta: { headers: { x-meta-data: true } }, // 传给数据提供者方法的附加信息 successNotification: (data, values, resource) ({ message: ${data.title} Successfully fetched., description: Success with no errors, type: success, }), errorNotification: (data, values, resource) ({ message: Something went wrong when getting ${data.id}, description: Error, type: error, }), });resource默认从路由推断多资源同名时可用identifier指定主匹配键meta可向getList等数据提供者方法传递额外信息如自定义请求头、GraphQL 查询字段数据提供者从方法参数中读取metasuccessNotification/errorNotification依赖NotificationProvider自定义请求成功 / 失败的通知内容liveMode、onLiveEvent、liveParams依赖LiveProvider用于实时订阅数据更新liveMode: auto自动刷新、manual手动处理overtimeOptions设置请求超时提示interval为轮询间隔毫秒onInterval为回调返回的overtime.elapsedTime在请求完成后变为undefined可用于请求超过 4 秒显示提示之类的交互。返回值速查useTable的返回值中除tableProps与searchFormProps外还暴露了可编程控制的状态返回值说明tableProps直接传给Table的 props含dataSource、loading、onChange、pagination、scroll。注意onChange内部负责排序 / 筛选 / 分页处理覆盖后需自行实现这些逻辑searchFormPropsAnt DesignFormpropsonFinish触发onSearchtableQuery底层useListReact QueryuseQuery的返回值如isSuccess、isFetchingsorters/setSorters当前排序状态与更新函数filters/setFilters当前筛选状态与更新函数支持merge/replace行为或函数式更新currentPage/setCurrentPage当前页码及更新函数分页关闭时为undefinedpageSize/setPageSize每页条数及更新函数分页关闭时为undefinedpageCount总页数分页关闭时为undefinedcreateLinkForSyncWithLocation根据pagination/sorters/filters生成可分享链接的函数overtime{ elapsedTime?: number }超时加载状态这些返回值在 useTable.ts 中有完整定义类型签名如setFilters支持behavior?: merge | replace可参考 Hook 文档 的 API 一节。常见问题如何处理关联数据当列表列需要展示关联资源名称如category.id→ 分类标题时用useMany批量拉取关联数据并用useSelect配合getDefaultFilter构建分类多选筛选。示例 list.tsx 展示了完整做法从tableProps.dataSource收集category.id列表 →useMany取分类 → 渲染时查表映射标题。如何做纯客户端筛选 / 排序分别设置filters.mode: off与sorters.mode: off即可关闭服务端筛选 / 排序完全复用 Ant DesignTable自带的filtersonFilter、sorter客户端能力适合数据量不大、不希望每次交互都发请求的场景。小结useTable把表格数据获取 分页 排序 筛选 搜索 URL 状态同步完整收敛到一个 Hook 中外层是 Ant DesignTable的零成本接入内层是 Refine 核心的useList数据请求与CrudSorting/CrudFilters统一模型。无论是用 table-antd-use-table 示例 快速起步还是深入 useTable 源码 理解其映射逻辑都能在真实后台项目中显著减少列表页的样板代码。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考