表格与列表体系

本文说明 art-design-pro-x-ui 中列表页的通用实现方式。它适合在新增管理页面、调整分页字段、排查列表刷新或复用列配置能力时阅读。

核心文件

文件	作用
`src/hooks/core/useTable.ts`	列表页数据请求、分页、搜索、刷新、缓存和错误状态管理
`src/hooks/core/useTableColumns.ts`	表格列显示、隐藏、排序、更新与重置
`src/utils/table/tableConfig.ts`	表格响应字段和分页请求字段的全局映射
`src/utils/table/tableCache.ts`	基于请求参数的列表缓存、过期清理和缓存失效策略
`src/utils/table/tableUtils.ts`	响应适配、分页同步、防抖搜索和错误处理工具
`src/store/modules/table.ts`	表格相关的全局状态

这套能力的目标是让标准列表页只关注业务字段、接口函数和页面交互，不在每个页面重复处理分页、加载状态、响应适配和列管理。

标准列表页主链路

一个标准列表页通常按下面的链路运行：

mermaid

flowchart TD
  A["页面定义搜索表单和列配置"] --> B["调用 useTable"]
  B --> C["执行 apiFn(searchParams)"]
  C --> D["响应适配与数据提取"]
  D --> E["同步 data 和 pagination"]
  E --> F["渲染表格与分页"]
  F --> G["搜索、重置、新增、编辑、删除后刷新"]

useTable 会维护 data、loading、error、searchParams、pagination 等状态，并根据配置决定是否立即请求、是否启用缓存、是否使用自定义响应适配器。

分页字段映射

默认请求分页字段来自 tableConfig.paginationKey：

paginationKey: {
  current: 'current',
  size: 'size'
}

默认响应字段会按优先级识别：

类型	默认候选字段
列表数据	`list`、`data`、`records`、`items`、`result`、`rows`
总条数	`total`、`count`
当前页	`current`、`page`、`pageNum`
每页数量	`size`、`pageSize`、`limit`

如果后端接口返回格式与默认约定不一致，优先在 useTable 的 transform.responseAdapter 中适配单个页面；只有当多个页面都使用同一套格式时，再调整 tableConfig.ts。

列配置管理

需要动态列时，在 useTable 中传入 columnsFactory，内部会调用 useTableColumns 生成列配置：

const {
  data,
  loading,
  pagination,
  columns,
  columnChecks,
  getData,
  search,
  resetSearch
} = useTable({
  core: {
    apiFn: fetchUserList,
    columnsFactory: () => [
      { prop: 'username', label: '用户名' },
      { prop: 'email', label: '邮箱' },
      { prop: 'status', label: '状态' }
    ]
  }
})

useTableColumns 支持：

能力	说明
`toggleColumn`	显示或隐藏单列、批量列
`updateColumn`	更新列标题、宽度、渲染配置等
`reorderColumns`	调整列顺序
`addColumn` / `removeColumn`	按运行时条件增删列
`resetColumns`	回到 `columnsFactory` 的初始列结构

特殊列 selection、expand、index 会被统一转换为内部 key，避免和业务字段冲突。

缓存策略

useTable 默认不启用缓存。列表数据变动频率低、查询条件稳定、接口成本较高时，可以开启：

useTable({
  core: {
    apiFn: fetchLogList
  },
  performance: {
    enableCache: true,
    cacheTime: 5 * 60 * 1000,
    maxCacheSize: 50
  }
})

缓存 key 基于请求参数生成，缓存项会记录访问次数、最后访问时间和标签。常见失效策略包括：

策略	适用场景
`CLEAR_ALL`	新增、批量导入、影响整批数据的操作
`CLEAR_CURRENT`	只影响当前查询条件下的单条数据
`CLEAR_PAGINATION`	数据顺序或总数变化，但搜索条件不变
`KEEP_ALL`	只读操作，不需要刷新缓存

启用缓存后，新增、编辑、删除等操作完成后要主动选择刷新策略，否则页面可能继续展示旧数据。

新增列表页建议

新增一个列表页时，推荐按下面顺序处理：

在 src/api 中封装接口函数，并按接口权限约定补充 permissionCode。
在 src/types/api 中补充接口类型，避免页面直接写松散对象。
在页面中定义搜索参数、列配置和操作按钮。
使用 useTable 接入请求、分页、搜索、刷新。
如果需要列显示控制，再接入 columnChecks 和列设置 UI。
如果接口返回结构特殊，先在当前页面写 responseAdapter，不要直接改全局配置。

常见问题

列表有数据但表格为空

优先检查接口返回中的列表字段是否能被 tableConfig.recordFields 识别。如果字段名不一致，为当前页面增加 responseAdapter。

分页总数不对

检查响应里的总数字段是否在 tableConfig.totalFields 中，或检查接口是否返回了分页对象嵌套结构。

搜索后页码没有回到第一页

检查页面是否调用了 search 或统一封装的搜索方法。手动改 searchParams 后直接调用 getData，可能不会执行搜索场景下的页码重置逻辑。

编辑后数据没有刷新

如果启用了缓存，检查编辑成功后的缓存失效策略；如果没有启用缓存，检查是否调用了列表刷新方法。

表格与列表体系 ​

核心文件 ​

标准列表页主链路 ​

分页字段映射 ​

列配置管理 ​

缓存策略 ​

新增列表页建议 ​

常见问题 ​

列表有数据但表格为空 ​

分页总数不对 ​

搜索后页码没有回到第一页 ​

编辑后数据没有刷新 ​

相关阅读 ​