请求与行为配置

tableConfig 中与列表请求、删除、分页、工具栏、表格属性相关的配置项。

列配置见列配置，序号列 / 多选列 / 操作列见附加列配置。

bordered

是否为表格区域（工具栏 + 表格 + 分页）显示外边框，样式与搜索区 searchConfig.bordered 一致。

属性	说明	类型	默认值
bordered	表格区域外边框	Boolean	false

// 页面级
tableConfig: {
  bordered: true
}

// 全局默认（app.use），页面 tableConfig.bordered 优先
app.use(AdminProTable, {
  tableConfig: { bordered: true }
})

与 tableProps.border 的区别：bordered 控制外层 table-box 卡片描边；tableProps.border 控制 el-table 单元格网格线。

requestConfig

列表请求配置，与分页、搜索条件合并后传给 api。

可在 app.use(AdminProTable, { requestConfig: { ... } }) 中配置全局默认值，单表 tableConfig.requestConfig 优先覆盖。详见全局 requestConfig。

属性	说明	类型	默认值
api	列表请求方法：`(params) => Promise`，params 默认包含分页与搜索条件；`pageParams: false` 时不包含分页字段；通常只在单表配置	Function	-
params	额外固定参数；支持对象或 `() => object`（函数形式可引用响应式变量）；全局与局部对象会浅合并	Object \| Function	{}
filterEmptyParams	是否过滤空搜索条件；默认过滤 `''`、`null`、`undefined`、空数组，设为 `false` 时搜索表单值会原样传入	Boolean	true
autoFetch	组件挂载后是否自动请求。设为 `false` 时需手动调用 `tableRef.refresh()`	Boolean	true
pageParams	是否自动携带分页参数；设为 `false` 时不传 `page/pageSize`（或自定义分页字段），并自动隐藏分页器	Boolean	true
pageKey	分页「当前页」参数字段名	String	'page'
pageSizeKey	分页「每页条数」参数字段名	String	'pageSize'
defaultPageSize	默认每页条数	Number	20
paramsFormat	请求参数最终格式化：`(params) => params`，在固定参数、分页参数、搜索条件合并后执行，早于 `beforeRequest`	Function	-
beforeRequest	请求前钩子：`(params) => params \| false`，可修改参数；返回 `false` 取消本次请求	Function	-
afterRequest	请求后钩子：`(res) => void \| res`，在 responseFormat 之前调用；return 新值则替换响应	Function	-
responseFormat	格式化接口返回：`(res) => ({ list, total })`；未配置时支持 `{ data: { list, total } }`、`{ list, total }`、`{ data: [] }`、`{ list: [] }` 或直接返回数组	Function	-
requestCompleted	请求结束回调：`({ success, list, total, res, error, params }) => void`，无论成功或失败都会触发	Function	-

基本用法

requestConfig: {
  api: getUserList,
  defaultPageSize: 20
}

额外固定参数

// 对象形式（静态）
requestConfig: {
  api: getUserList,
  params: { deptId: 10, type: 'admin' }
}

// 函数形式（引用响应式变量）
const deptId = ref(null)
requestConfig: {
  api: getUserList,
  params: () => ({ deptId: deptId.value })
}

filterEmptyParams — 是否过滤空搜索条件

默认情况下，搜索条件中的空字符串、null、undefined、空数组不会传给列表接口：

requestConfig: {
  api: getUserList
}

如果接口需要接收空值，可以关闭过滤：

requestConfig: {
  api: getUserList,
  filterEmptyParams: false
}

关闭后，搜索表单当前值会原样参与请求参数合并。可在全局 requestConfig 或单表 requestConfig 中配置：

app.use(AdminProTable, {
  requestConfig: { filterEmptyParams: false }
})

pageParams: false — 不传分页参数

默认情况下，列表请求会自动携带分页参数：page 和 pageSize（或全局 / 局部配置的 pageKey、pageSizeKey）。如果某些接口不分页，可以关闭分页参数：

requestConfig: {
  api: getDictList,
  pageParams: false
}

关闭后，请求参数只会包含 requestConfig.params 与搜索条件，不会再自动附加 page、pageSize，表格底部分页器也会自动隐藏。

pageParams 和 footerConfig.showPagination 的区别：

pageParams: false 表示接口本身不分页：不传分页参数，并强制隐藏分页器。
footerConfig.showPagination: false 只控制分页器显示：请求仍会按 pageParams 配置决定是否携带分页参数。

如果项目内大部分接口都不需要分页，可在全局 requestConfig 中关闭：

app.use(AdminProTable, {
  requestConfig: { pageParams: false }
})

单个表格仍可覆盖全局配置：

requestConfig: {
  api: getPagedUserList,
  pageParams: true
}

autoFetch: false — 延迟加载

需要先拿到外部数据再加载表格时：

vue

<template>
  <pro-table ref="tableRef" :table-config="tableConfig" />
</template>
<script setup>
import { ref, onMounted } from 'vue'
const tableRef = ref(null)
const orgId = ref(null)
const tableConfig = {
  requestConfig: {
    autoFetch: false,
    api: getUserList,
    params: () => ({ orgId: orgId.value })
  }
}
onMounted(async () => {
  const res = await getOrgInfo()
  orgId.value = res.id
  tableRef.value?.refresh()
})
</script>

paramsFormat — 最终格式化请求参数

paramsFormat 会在固定参数、分页参数、搜索条件合并完成后执行，适合统一转换字段名、类型或删除不需要的字段。它早于 beforeRequest 执行。

requestConfig: {
  api: getUserList,
  paramsFormat: (params) => ({
    ...params,
    status: params.status === '' ? undefined : Number(params.status),
    source: 'admin'
  })
}

如果返回 undefined 或 null，组件会继续使用原参数。

paramsFormat 和 beforeRequest 的区别：

paramsFormat 只建议用于纯参数转换，例如字段改名、类型转换、补充固定字段。
beforeRequest 用于请求前拦截，可以继续修改参数，也可以返回 false 取消本次请求。

执行顺序：参数合并 → paramsFormat → beforeRequest → api。

可在全局 requestConfig.paramsFormat 中统一处理，单表配置会覆盖全局：

app.use(AdminProTable, {
  requestConfig: {
    paramsFormat: (params) => ({ ...params, source: 'admin' })
  }
})

beforeRequest — 拦截或修改参数

requestConfig: {
  api: getUserList,
  beforeRequest: (params) => {
    if (params.dateRange?.length === 2) {
      params.startTime = params.dateRange[0]
      params.endTime = params.dateRange[1]
      delete params.dateRange
    }
    if (!params.orgId) return false  // 返回 false 取消请求
    return params
  }
}

afterRequest 与 responseFormat

afterRequest 和 responseFormat 都在接口返回后执行，但职责不同：

afterRequest 用于预处理接口原始响应，例如解密、解包、兼容特殊响应结构；它的返回值会作为后续响应继续处理。
responseFormat 用于把响应解析成表格需要的 { list, total }。

执行顺序：api → afterRequest → responseFormat → 渲染表格。

requestConfig: {
  api: getUserList,
  afterRequest: (res) => res.result,
  responseFormat: (res) => ({
    list: res.records,
    total: res.total
  })
}

responseFormat — 自定义响应解析

requestConfig: {
  api: getUserList,
  responseFormat: (res) => ({
    list: res.data.records,
    total: res.data.total
  })
}

requestCompleted — 请求结束后统一处理

适合在列表请求结束后统一做收尾逻辑。成功时可根据当前页数据做金额合计、数量汇总；失败时也能拿到错误信息。

requestConfig: {
  api: getOrderList,
  requestCompleted: ({ success, list, total, res, error, params }) => {
    if (success) {
      pageSummary.value.totalAmount = list.reduce((sum, item) => {
        return sum + Number(item.amount || 0)
      }, 0)
      pageSummary.value.currentCount = list.length
      pageSummary.value.serverTotalAmount = res?.data?.totalAmount ?? 0

      console.log('总条数', total)
    } else {
      console.error('列表请求失败', error)
    }

    console.log('请求参数', params)
  }
}

deleteConfig

配置 api 后，操作列「删除」和工具栏「批量删除」才会生效。

属性	说明	类型	默认值
api	删除方法；单删有 paramKey 时传 `{ [paramKey]: row[idField] }`，批量删除有 paramKey 时传 `{ [paramKey]: ids[] }`；不配 paramKey 时单删传 row，批量传 rows[]	Function	-
idField	行数据主键字段名	String	'id'
paramKey	请求参数中主键字段名（如 `'id'`）；不配则 api 接收整行 row	String	-
confirmDialog	删除确认框配置，见下方 confirmDialog	Object	-
paramsFormat	提交前对参数做转换：`(params) => any`	Function	-
responseFormat	响应后做转换：`(res) => any`	Function	-

// 常见用法：单删传 { id: row.id }，批量删除传 { id: [row1.id, row2.id] }
deleteConfig: {
  api: deleteUser,
  idField: 'id',
  paramKey: 'id'
}

// 后端批量字段名为 ids：单删传 { ids: row.id }，批量删除传 { ids: [row1.id, row2.id] }
deleteConfig: {
  api: deleteQuestion,
  idField: 'id',
  paramKey: 'ids',
  paramsFormat: (params) => ({
    ids: Array.isArray(params.ids) ? params.ids : [params.ids]
  })
}

// 传整行 row / rows（不配 paramKey）
deleteConfig: {
  api: (row) => deleteUser({ userId: row.id, type: row.type })
}

// 自定义删除确认框
deleteConfig: {
  api: deleteUser,
  idField: 'id',
  paramKey: 'id',
  confirmDialog: {
    title: '删除用户',
    message: (row) => `确定删除用户「${row.name}」吗？`,
    batchTitle: '批量删除用户',
    batchMessage: (rows) => `确定删除选中的 ${rows.length} 位用户吗？`,
    confirmButtonText: '立即删除',
    cancelButtonText: '取消',
    type: 'warning'
  }
}

// 提交前做参数转换
deleteConfig: {
  api: deleteUser,
  idField: 'id',
  paramsFormat: (params) => ({ ...params, source: 'admin' })
}

删除响应判断

删除接口返回对象中包含全局 codeKey 字段时，组件会根据全局 successCode 判断是否删除成功：

String(res[codeKey]) === String(successCode)：提示删除成功并刷新列表。
不相等：提示 res[messageKey] 或 res.message，不会提示删除成功，也不会刷新列表。
接口请求抛错：提示错误信息。

app.use(AdminProTable, {
  successCode: 1,
  codeKey: 'code',
  messageKey: 'msg'
})

// 返回 { code: 0, msg: '请选择要删除的题目' } 时会提示该 msg，并按失败处理
deleteConfig: {
  api: deleteQuestion,
  idField: 'id',
  paramKey: 'id'
}

confirmDialog

deleteConfig.confirmDialog 用于统一配置单条删除和批量删除时的确认弹窗文案与按钮。

属性	说明	类型	默认值
title	单条删除确认框标题；支持 `string` 或 `(row) => string`	String \| Function	`'删除确认'`
message	单条删除确认内容；支持 `string` 或 `(row) => string`	String \| Function	`'确定删除该条数据吗？'`
batchTitle	批量删除确认框标题；支持 `string` 或 `(rows) => string`；不配时复用 `title`	String \| Function	`title`
batchMessage	批量删除确认内容；支持 `string` 或 `(rows) => string`；不配时默认 `确定删除选中的 n 条数据吗？`	String \| Function	-
confirmButtonText	确认按钮文案	String	`'确定'`
cancelButtonText	取消按钮文案	String	`'取消'`
type	MessageBox 类型	String	`'warning'`

footerConfig

表格底部分页区域配置。

属性	说明	类型	默认值
show	是否显示底部分页区	Boolean	true
showPagination	是否显示分页器	Boolean	true
showRefresh	是否显示刷新按钮	Boolean	true
pageSizes	每页条数可选值	Array	[10, 20, 50, 100]
paginationLayout	分页器布局，同 Element Plus Pagination layout	String	'total, sizes, prev, pager, next, jumper'

// 隐藏分页器只保留刷新按钮
footerConfig: { showPagination: false, showRefresh: true }

// 简化布局
footerConfig: {
  pageSizes: [10, 20, 50],
  paginationLayout: 'total, prev, pager, next'
}

// 完全隐藏底部
footerConfig: { show: false }

toolbarConfig

表格上方工具栏：左侧为添加/删除/返回等业务按钮，右侧为刷新、搜索显隐、列设置等小工具。

支持通过 app.use(AdminProTable, { toolbarConfig }) 配置全局默认，页面 tableConfig.toolbarConfig 浅合并覆盖（页面级优先）。

属性	说明	类型	默认值
show	是否显示工具栏区域	Boolean	true
showBack	是否显示「返回」按钮，点击触发 `@back` 事件	Boolean	false
showAdd	是否显示「添加」按钮（需配置 formConfig）	Boolean	true
showDelete	是否显示「批量删除」按钮（需配置 deleteConfig.api）	Boolean	true
showTools	右侧小工具总开关（刷新 / 搜索显隐 / 列设置）；`false` 时三个都不显示	Boolean	true
showRefreshTool	右侧「刷新」按钮，点击重新请求列表	Boolean	true
showSearchToggle	右侧「显示/隐藏搜索」；无 `searchConfig` 时默认不显示，有搜索区时默认显示	Boolean	有搜索区时 true
showColumnSetting	右侧「列设置」按钮（显隐 + 拖拽排序）	Boolean	true
columnSettingKey	列设置 localStorage 缓存 key；配置后确定写入、重置清除；不配则仅本次会话生效。建议按页面单独配置，避免多列表互相覆盖	String	''
backText	返回按钮文案	String	'返回'
addText	添加按钮文案	String	'添加'
deleteText	删除按钮文案	String	'删除'
addPermission	添加按钮权限码，见按钮权限	String \| String[]	-
deletePermission	批量删除按钮权限码	String \| String[]	-
backPermission	返回按钮权限码	String \| String[]	-

// 全局默认（main.js）
app.use(AdminProTable, {
  toolbarConfig: {
    showTools: true,
    showRefreshTool: true,
    showColumnSetting: true
  }
})

// 常见配置（页面级覆盖全局）
toolbarConfig: {
  showAdd: true,
  showDelete: true,
  addText: '新增用户',
  // 按页面唯一，避免多个列表互相覆盖
  columnSettingKey: 'user-list-columns'
}

// 一键关闭右侧三个小工具（刷新 / 搜索显隐 / 列设置）
toolbarConfig: {
  showTools: false
}

// 只关某一个
toolbarConfig: {
  showRefreshTool: false,
  showColumnSetting: false
  // 无 searchConfig 时 showSearchToggle 本身就不会出现
}

// 列表钻取场景
toolbarConfig: { showBack: true, showAdd: true }
// <pro-table @back="router.back()" />

// 配合权限码
toolbarConfig: {
  showAdd: true,
  addPermission: 'user:add',
  deletePermission: 'user:delete'
}

tableProps

透传给 el-table 的属性，支持 Element Plus Table 全部属性。

ProTable 内部默认会给表格设置 height: '100%'，表格数据较多时会在表格主体区域内滚动，并保持底部分页区域固定在下方。一般情况下不需要手动配置 tableProps.height。如果需要固定像素高度或最大高度，可以通过 height / maxHeight 覆盖默认行为。

// 默认情况下无需设置 height，表格会自动填满剩余区域并滚动
tableProps: {
  border: true,
  stripe: true,
  size: 'small',
  highlightCurrentRow: true,
  rowClassName: ({ row }) => row.status === 0 ? 'disabled-row' : ''
}

// 需要固定高度时再显式配置
tableProps: {
  height: 400
}

// 或限制最大高度
tableProps: {
  maxHeight: 600
}

全局 requestConfig

requestConfig 的全部属性都支持在 app.use(AdminProTable, options) 中全局配置，单表 tableConfig.requestConfig 优先覆盖。

合并规则

text

局部 tableConfig.requestConfig > 全局 requestConfig > 旧版顶层字段 > 组件内置默认值

普通字段（pageKey、filterEmptyParams、autoFetch 等）：局部有值则覆盖全局。
params 对象：全局与局部浅合并，同名 key 以局部为准。
函数类配置（paramsFormat、beforeRequest、afterRequest、responseFormat、requestCompleted）：局部有值则覆盖全局，不会链式调用。
api：通常只在单表配置，全局一般不设置。

旧版顶层字段（仍兼容）

以下字段仍可在 app.use 顶层直接配置，效果等同于写入 requestConfig 对应属性；若 requestConfig 中已显式配置同名字段，以 requestConfig 为准：

旧版顶层字段	对应 requestConfig 属性
`defaultPageSize`	`defaultPageSize`
`pageKey`	`pageKey`
`pageSizeKey`	`pageSizeKey`
`pageParams`	`pageParams`
`filterEmptyParams`	`filterEmptyParams`
`responseFormat`	`responseFormat`

新项目中建议统一使用 requestConfig 对象，避免混用。

全局配置

以下属性可在 app.use(AdminProTable, {...}) 中全局设置，单表配置优先于全局。完整说明见全局 requestConfig 与快速开始 - 全局配置。

全局属性	对应单表配置	说明
`requestConfig`	`tableConfig.requestConfig`	列表请求全局默认；`params` 对象浅合并，其余字段局部覆盖
`defaultPageSize`	`requestConfig.defaultPageSize`	旧版写法，推荐放入 `requestConfig`
`pageKey`	`requestConfig.pageKey`	旧版写法，推荐放入 `requestConfig`
`pageSizeKey`	`requestConfig.pageSizeKey`	旧版写法，推荐放入 `requestConfig`
`pageParams`	`requestConfig.pageParams`	旧版写法，推荐放入 `requestConfig`
`filterEmptyParams`	`requestConfig.filterEmptyParams`	旧版写法，推荐放入 `requestConfig`
`responseFormat`	`requestConfig.responseFormat`	旧版写法，推荐放入 `requestConfig`
`pageSizes`	`footerConfig.pageSizes`	分页器每页条数选项
`footerConfig`	`tableConfig.footerConfig`	底栏配置
`tableProps`	`tableConfig.tableProps`	表格属性（合并覆盖）
`emptyText`	`tableConfig.emptyText`	空数据提示
`searchConfig`	`searchConfig`	搜索表单默认配置
`formConfig`	`formConfig`	表单弹层默认配置
`uploadConfig`	各区域 `uploadConfig`	上传默认配置
`hasPermission`	工具栏 / 操作列权限码	权限校验函数
`successCode` / `codeKey` / `messageKey`	表单 / 删除接口	接口状态码与消息字段

请求与行为配置 ​

bordered ​

requestConfig ​

基本用法 ​

额外固定参数 ​

filterEmptyParams — 是否过滤空搜索条件 ​

pageParams: false — 不传分页参数 ​

autoFetch: false — 延迟加载 ​

paramsFormat — 最终格式化请求参数 ​

beforeRequest — 拦截或修改参数 ​

afterRequest 与 responseFormat ​

responseFormat — 自定义响应解析 ​

requestCompleted — 请求结束后统一处理 ​

deleteConfig ​

删除响应判断 ​

confirmDialog ​

footerConfig ​

toolbarConfig ​

tableProps ​

全局 requestConfig ​

合并规则 ​

推荐写法 ​

旧版顶层字段（仍兼容） ​

全局配置 ​