useTable Hook

useTable 是一个基于 Ant Design、结合自定义逻辑的表格管理 Hook，在传统表格场景中提供了包括地址栏持久化、动态列显示以及搜索分页等常见功能，能让你轻松构建可复制链接的可共享状态表格。

主要特性

地址栏参数同步
- 每当你修改分页、搜索、列筛选等参数时，useTable 都会更新到浏览器地址栏的 query 字符串中（如 ?current=2&size=10&keyword=abc）。
- 只需复制当前 URL，到其他浏览器或重新打开页面时，仍能显示相同的筛选和分页状态。不会丢失页面状态。
动态列管理
- 通过 columnChecks 与 setColumnChecks 可自由控制列的显示/隐藏。
- 只需在 UI 层提供复选框，用户就能自行选择表格列。
搜索/分页集成
- 自动提供 searchProps.form 用于与 AntD Form 绑定。
- 修改搜索条件或点击下一页时，参数会同步到地址栏并自动发起请求更新表格。
自动加行号、数据转化
- 内部支持一个 transformer 回调，可对后端返回的数据进行二次处理（如添加 index、字段映射等）。

函数签名


function useTable<A extends AntDesign.TableApiFn>(
  config: AntDesign.AntDesignTableConfig<A>,
  paginationConfig?: Omit<TablePaginationConfig, 'current' | 'onChange' | 'pageSize' | 'total'>
)

泛型参数：

A: 后端接口函数类型，形如 (params) => Promise<{ data: { current, records, size, total } }>。

参数说明：

config: 必填，表格的核心配置（apiFn、apiParams、columns、immediate等）。
paginationConfig: 可选，用于传给 AntD Table 的分页配置。

返回值

字段	类型	说明
`columnChecks`	`AntDesign.TableColumnCheck[]`	列的可见性状态数组。每个元素拥有 `{ key: string; title: string; checked: boolean }`。根据 `checked` 的值来判断该列是否展示。
`data`	`AntDesign.TableData[]`	整合后端接口数据 + `transformer` 处理的最终表格数据。如若 `transformer` 添加了行号，则在数据中会出现 `index` 属性。
`empty`	`boolean`	当前表格数据是否为空 (`data.length === 0`)。
`run`	`(isResetCurrent?: boolean) => Promise<void>`	手动触发表格请求，可通过可选参数 `isResetCurrent` 来决定是否重置到第一页。主要在搜索、刷新等场景使用。
`searchParams`	`Parameters<A>[0]`	包含当前查询条件（分页 + 搜索项）的对象，会在地址栏同步维护。如 `?current=2&keyword=abc`。仅需复制完整 URL，便可在他处恢复相同过滤、分页状态。
`searchProps`	`{ form, reset, search, searchParams }`	与 AntD Form 配合的属性对象，用来管理搜索表单。详见下表 searchProps。
`setColumnChecks`	`(checks: AntDesign.TableColumnCheck[]) => void`	更新列可见性。通常在 UI 层提供勾选或复选框，让用户选择所需列。
`tableProps`	`{ columns, dataSource, loading, pagination, rowKey }`	给 `<Table {...tableProps} />` 使用的属性集合。详见下表 tableProps。

`searchProps` 详细

字段	类型	说明
`form`	`FormInstance<Parameters<A>[0]>`	一个 AntD 的 Form 实例，可与 `<Form form={searchProps.form}>` 结合，使用 `initialValues={searchParams}` 等来同步当前地址栏参数到输入项中。刷新或复制链接后，表单字段也保持不变。
`reset`	`() => void`	重置搜索表单与内部的 `searchParams`，会恢复到 `apiParams` 初始值，并触发一次请求。
`search`	`() => Promise<void>`	等效于 `run()`，在校验表单后执行一次请求，可用于表单提交时调用。
`searchParams`	`Parameters<A>[0]`	与外层 `searchParams` 相同，已包含当前分页和搜索字段，可在需要场景下直接读取。

`tableProps` 详细

字段	类型	说明
`columns`	`TableColumn<AntDesign.TableDataWithIndex<GetTableData<A>>>[]`	根据 `columnChecks` 和 `columns` 函数返回的初始列合并过滤后的列表，只有 `checked: true` 的列才会显示。
`dataSource`	`AntDesign.TableData[]`	表格数据源，已包含页码计算索引、或其他自定义处理后的记录（如 `index` 字段等）。
`loading`	`boolean`	是否处于加载中状态，供 AntD `<Table loading={tableProps.loading} />`使用。
`pagination`	`TablePaginationConfig`	分页配置，内部自动注入 `onChange`、`current`、`pageSize`、`total` 等，与后端数据和地址栏保持同步。只需展开使用即可，示例：`<Table pagination={tableProps.pagination} ... />`。
`rowKey`	`keyof GetTableData<A> \| 'id'`	用来唯一标识每条数据。默认值为 `id`，如果后端主键字段并非 `id`，可通过 `config.rowKey` 自行指定。

核心使用方式

初始化
```
const {
  columnChecks,
  data,
  empty,
  run,
  searchProps,
  setColumnChecks,
  tableProps
} = useTable(
  {
    apiFn: fetchGetUserList,
    apiParams: { current: 1, size: 10, userName: null },
    columns: () => [...],
    immediate: true
  },
  { showQuickJumper: true }
);
```
- apiFn: 获取表格数据的异步接口。
- apiParams: 搜索&分页等初始参数，地址栏也会基于此生成初始状态。
- columns: 返回列的定义数组，可配合行渲染器 render、列 key 等。
- immediate: 是否在组件挂载时立即发起请求，默认 true。
- 传给表格的 paginationConfig 示例：{ showQuickJumper: true }。

绑定搜索表单


const { form, reset, search, searchParams } = searchProps;
 
return (
  <Form
    form={form}
    initialValues={searchParams} // 关键: 表单初始值设为当前的搜索参数，保证复制链接后不会丢失搜索条件
    onFinish={() => search()}    // 或 run()
  >
    <Form.Item name="userName">
      <Input placeholder="用户名" />
    </Form.Item>
    <Button htmlType="submit">搜索</Button>
    <Button onClick={reset}>重置</Button>
  </Form>
);

使用 initialValues={searchParams}，在复制链接到其他页面打开时，表单仍能保持同样的输入值。

显示表格
```
<Table {...tableProps} />
```
- 只需将 tableProps 展开传给 <Table> 即可。
- 由于内置了分页与加载状态管理，开发者无需手动处理 onChange(page) 等事件。

列管理（可选）


<Checkbox.Group
  value={columnChecks.filter(i => i.checked).map(i => i.key)}
  onChange={vals => {
    const newChecks = columnChecks.map(chk => ({
      ...chk,
      checked: vals.includes(chk.key)
    }));
    setColumnChecks(newChecks);
  }}
>
  {columnChecks.map(chk => (
    <Checkbox key={chk.key} value={chk.key}>
      {chk.title}
    </Checkbox>
  ))}
</Checkbox.Group>

columnChecks 中的 checked 值会决定哪些列在 tableProps.columns 中呈现。

为什么可以“复制链接不丢失状态”

Hook 内部通过 useSearchParams 将搜索和分页信息写入地址栏。
当用户打开此链接时，useSearchParams 会从 URL 解析同样的搜索和分页信息并自动交给 useTable。
若在 <Form> 中使用 initialValues={searchParams}, 表单字段也会填充同样数据，完全还原之前的状态。

总结

useTable 让我们在 AntD + React 场景下构建强大且可共享的表格搜索功能变得简单且灵活：

地址栏持久化：修改分页或搜索后自动更新 URL，可复制链接给他人；刷新也不会丢失状态。
动态列管理：通过 columnChecks 自定义哪些列要显示。
表单集成：表单数据实时写进地址栏，使搜索逻辑与业务管理表单紧密结合。
自动分页 & 数据转换：paginationConfig 及 transformer 帮助你轻松处理分页及数据映射。

只需要在调用时指定好后端接口、初始搜索参数及列配置，再根据返回的各项属性进行必要的 UI 拼装，就可以完成一个功能完善、可自由扩展的列表页面，大幅提升开发效率与可维护性。