vben admin BasicTable组件

以下是 BasicTable 的常用使用指南，可作为日常开发的速查手册。

1. 快速上手

ts 复制代码

const [registerTable, { reload, setProps, clearSelectedRowKeys, getDataSource }] =
  useTable({
    title: '示例列表',
    columns,
    api: fetchListApi,
    rowKey: 'id',
  });

vue 复制代码

<BasicTable @register="registerTable">
  <template #toolbar> ... </template>
  <template #bodyCell="{ column, record }"> ... </template>
</BasicTable>

2. useTable 配置项（常用）

选项	说明
`columns`	列定义，支持 `title/dataIndex/width/fixed/ellipsis/sorter/customRender` 等 Ant Design Table 属性
`api`	异步请求函数，返回 `{ items, total }` 或自定义 `fetchSetting` 映射
`rowKey`	唯一标识，字符串或函数
`title`	表格标题，可配 `titleHelpMessage`
`striped`	斑马纹
`bordered`	边框
`maxHeight`、`canResize`	控制高度和滚动行为
`showIndexColumn` / `indexColumnProps`	序号列及其配置
`actionColumn`	操作列配置（`slots.customRender`）
`pagination`	false/对象/Ant Design Pagination 属性
`useSearchForm` + `formConfig`	内联搜索表单（ schemas、labelWidth、autoSubmit 等）
`showTableSetting` + `tableSetting`	右上角工具区（列显示、序号列、勾选列、刷新、尺寸、全屏）
`rowSelection`	多选配置（`type`、`preserveSelectedRowKeys`、`onChange` 等）
`beforeFetch` / `afterFetch`	请求入参、出参自定义处理
`handleSearchInfoFn`	搜索参数统一加工
`fetchSetting`	`pageField/sizeField/listField/totalField` 自定义字段映射
`searchInfo` / `defSort`	额外查询参数与默认排序
`immediate`	是否初始化自动请求（默认 true）
`clearSelectOnPageChange`	翻页是否清空选择
`clickToRowSelect`	点击整行触发选中

3. useTable 返回的常用方法

方法	说明
`reload(opt?)`	重新拉取数据，可传 `page`, `searchInfo`
`setProps(partial)`	动态调整配置（开关多选、改变列、分页等）
`setColumns(columns)`	动态替换列定义
`getColumns()` / `getDataSource()`	获取当前列、数据
`clearSelectedRowKeys()` / `getSelectRows()`	清空或获取当前已选行
`setPagination(pagination)`	更新分页配置
`setLoading(bool)`	手动控制 loading
`getForm()`	当启用 `useSearchForm` 时获取表单实例（`submit`, `reset`, `setFieldsValue`...）

4. 插槽

插槽	用途
`toolbar`	标题右侧自定义按钮区
`tableTitle` / `headerTop`	自定义标题区域或顶部块
`bodyCell`	单元格渲染 `slotProps = { text, record, column, index }`
`expandedRowRender`	可展开行内容
`#emptyText`	空状态

5. 典型场景示例

5.1 带搜索表单

ts 复制代码

useTable({
  useSearchForm: true,
  formConfig: {
    labelWidth: 100,
    schemas: [
      { field: 'name', component: 'Input', label: '名称' },
      { field: 'status', component: 'Select', label: '状态', componentProps: { options } },
    ],
  },
});

5.2 列设置 + 序号列 + 多选

ts 复制代码

useTable({
  showTableSetting: true,
  showIndexColumn: true,
  rowSelection: {
    type: 'checkbox',
    preserveSelectedRowKeys: true,
    onChange: (keys) => (selectedKeys.value = keys as string[]),
  },
});

5.3 自定义请求字段

ts 复制代码

useTable({
  api: fetchList,
  fetchSetting: {
    pageField: 'pageNum',
    sizeField: 'pageSize',
    listField: 'records',
    totalField: 'total',
  },
});

5.4 内联操作列

ts 复制代码

const columns = [
  ...
  {
    title: '操作',
    dataIndex: 'action',
    slots: { customRender: 'action' },
    width: 120,
  },
];

vue 复制代码

<template #bodyCell="{ column, record }">
  <template v-if="column.dataIndex === 'action'">
    <a @click="handleEdit(record)">编辑</a>
    <a-divider type="vertical" />
    <a @click="handleDetail(record)">详情</a>
  </template>
</template>

6. 小贴士

列宽：固定列必须指定 width，否则拖动/隐藏后容易错位。
多选默认关闭 ：可以先配置 rowSelection，再用 setProps({ rowSelection: undefined }) 控制默认状态。
刷新按钮 ：通过 tableSetting.redo = true，并在 api 中直接使用 reload() 即可。
防止多次请求 ：beforeFetch 中合并查询参数，避免组件外频繁 setProps。
复杂场景 ：结合 useModal、Authority、contextHolder 等实现 CRUD、导入导出等业务闭环。

以上即为 BasicTable 的核心用法与属性说明，覆盖了大多数后台列表开发场景，可按需裁剪。