Vue 3 中后台表格组件封装实战：从 loading 到分页的完整设计

管理后台开发中，表格组件封装是绕不开的一步。一个中后台项目里，列表页少说十几个，多则几十个，如果不做封装，每个页面都要重复写 loading 状态、分页逻辑、空数据判断、操作列按钮和批量选择。页面代码一多，维护成本直接翻倍。

这篇文章讲的不是 Element Plus 基础用法，而是把表格组件封装成团队内部可复用业务组件的完整思路，包括 props / slots / events / expose 四层设计、搜索表单联动、批量操作、动态列、性能优化和常见坑位排查。示例代码基于 Vue 3 + Element Plus + Vite，核心思路同样可以迁移到 React + Ant Design。

1. 核心能力速览

封装表格组件不是做一个万能组件，而是把列表页里反复出现的逻辑抽成公共能力。先看一张能力速览表：

文章下面会按这套设计一步步给出代码，读者可以直接复制到项目里跑通，再根据后端返回结构调整字段解析逻辑。

2. 适用场景与封装边界

表格组件封装最适合管理后台的 CRUD 列表页、查询统计页和数据导出页。这些页面有共同特征：一个查询表单、一张表格、一个分页器、若干操作按钮，数据从接口拉取，展示结构高度相似。

不适合封装成通用组件的场景也要明确：复杂透视表、Excel 级在线编辑、树形大数据表格、需要大量自定义表头的报表。这些场景更适合直接用 Element Plus 或 Ant Design 的原生表格，或者上专业表格库，硬套一层封装只会增加理解成本。

封装边界要守住三条原则：

1. 业务逻辑不能写死在组件里。状态标签、操作按钮、导出逻辑都应该通过插槽或事件交给父组件处理。
2. 组件不感知具体后端字段。返回结构解析要做兼容，但表格列配置必须由父组件传入。
3. 不要做万能组件。props 数量控制在合理范围，超过二十个就要考虑是不是拆得太粗了。

过度封装的典型表现是：组件内部塞了搜索表单、权限判断、导入导出、字典翻译，页面只要稍微不一样就会写一堆 if else。封装表格组件的正确姿势是"表格只负责表格的事"，其他能力用插槽和事件扩展。

3. 环境准备与目录结构

本文示例基于 Vue 3 + Element Plus，先创建一个标准项目：

npm create vite@latest table-demo -- --template vue cd table-demo npm install element-plus

如果使用 TypeScript，再加类型依赖：

npm install -D @types/node

目录结构建议按组件库的方式组织，不要把所有代码堆在 App.vue 里：

src/ ├── components/ │ └── BaseTable/ │ ├── index.vue # 表格组件主入口 │ ├── types.ts # Props / 列配置类型定义 │ └── README.md # 组件使用文档 ├── pages/ │ └── user/ │ ├── index.vue # 用户列表页 │ ├── columns.ts # 列配置独立文件 │ └── api.ts # 接口请求函数 └── api/ └── request.ts # axios 实例封装

列配置独立成文件是很容易被忽略的好习惯。列表页的列会频繁调整，单独放一个 columns.ts，改列宽、加字段、调顺序都更直观，也方便后续做动态列配置。

接口请求函数单独放在 api.ts，方便复用和 mock。BaseTable 只接收一个 api 函数，不关心请求是 axios 还是 fetch 实现的。

4. 封装思路：props / slots / events / expose 四层设计

表格组件封装的核心是设计好对外接口。我把 BaseTable 的对外能力分成四层：

4.1 props：控制行为和外观

props 负责告诉组件"你要展示什么、怎么请求、是否支持分页和多选"。核心 props 包括：

4.2 slots：扩展单元格和工具栏

插槽解决"组件显示不了所有业务场景"的问题。BaseTable 需要提供两类插槽：

• 具名单元格插槽：名字和列配置里的 slot 字段对应，父组件可以用#status、#action这样的方式自由定制单元格内容。
• toolbar 插槽：放在表格上方，用于放新增、批量删除、导出等按钮，同时把当前选中行透传给父组件。

4.3 events：通知父组件业务事件

父组件需要知道表格内部发生了什么，events 负责对外通知。常用事件包括：

• selection-change：多选变化时触发，传入选中的行数组
• row-click：行点击事件
• load-success：数据加载成功
• load-error：数据加载失败

4.4 expose：暴露刷新方法

表格组件内部维护了 page、pageSize、tableData 等状态，父组件不能直接改，但需要触发刷新。通过 defineExpose 暴露 refresh 和 reload 方法，父组件调用tableRef.value.refresh()就能重置到第一页并重新请求。

这四个层次想清楚，封装就完成了一半。下面直接进入代码实现。

5. 基础表格组件完整代码实现

BaseTable 组件分为模板和脚本两部分。模板负责渲染表格、插槽和分页器，脚本负责数据请求、分页控制和事件转发。

5.1 模板部分

<template> <div class="base-table"> <div v-if="$slots.toolbar" class="base-table__toolbar"> <slot name="toolbar" :selected-rows="selectedRows"></slot> </div> <el-table v-loading="loading" :data="tableData" :row-key="rowKey" :border="border" :stripe="stripe" :height="height" :max-height="maxHeight" @selection-change="handleSelectionChange" @row-click="handleRowClick" > <el-table-column v-if="showSelection" type="selection" width="50" :reserve-selection="true" /> <template v-for="col in columns" :key="col.prop || col.label"> <el-table-column :prop="col.prop" :label="col.label" :width="col.width" :min-width="col.minWidth" :fixed="col.fixed" :sortable="col.sortable" :align="col.align || 'left'" :show-overflow-tooltip="col.ellipsis !== false" > <template #default="scope"> <slot :name="col.slot || col.prop" :row="scope.row" :index="scope.$index" :value="scope.row[col.prop]" > <span>{{ scope.row[col.prop] }}</span> </slot> </template> </el-table-column> </template> <slot name="append-column"></slot> </el-table> <div v-if="showPagination" class="base-table__pagination"> <el-pagination :current-page="pageInfo.page" :page-size="pageInfo.pageSize" :total="pageInfo.total" :page-sizes="pageSizes" :layout="paginationLayout" background @current-change="handlePageChange" @size-change="handleSizeChange" /> </div> </div> </template>

这里有几个细节需要说明。

第一，col.slot || col.prop作为插槽名的设计。如果列配置里写了slot: 'status'，父组件用#status定制；如果没写，默认用 prop 作为插槽名，父组件依然可以通过#name覆盖默认展示，这个约定很实用。

第二，show-overflow-tooltip用col.ellipsis !== false控制。遇到长文本时默认开启省略提示，但某些列比如操作列并不需要，在列配置里传ellipsis: false关闭即可。

第三，append-column插槽用于追加操作列等场景。列配置里写 action 列也行，但操作列往往要放在最后，并且要做 fixed="right"，单独用插槽更灵活。

5.2 脚本部分

<script setup> import { ref, watch, onMounted } from 'vue' const props = defineProps({ columns: { type: Array, required: true }, api: { type: Function, required: true }, queryParams: { type: Object, default: () => ({}) }, showPagination: { type: Boolean, default: true }, showSelection: { type: Boolean, default: false }, pageSizes: { type: Array, default: () => [10, 20, 50, 100] }, defaultPageSize: { type: Number, default: 10 }, rowKey: { type: String, default: 'id' }, border: { type: Boolean, default: false }, stripe: { type: Boolean, default: false }, height: { type: [String, Number], default: null }, maxHeight: { type: [String, Number], default: null }, paginationLayout: { type: String, default: 'total, sizes, prev, pager, next, jumper' }, immediate: { type: Boolean, default: true } }) const emit = defineEmits(['selection-change', 'row-click', 'load-success', 'load-error']) const loading = ref(false) const tableData = ref([]) const selectedRows = ref([]) const pageInfo = ref({ page: 1, pageSize: props.defaultPageSize, total: 0 }) const fetchData = async () => { loading.value = true try { const params = { page: pageInfo.value.page, pageSize: pageInfo.value.pageSize, ...props.queryParams } const res = await props.api(params) const list = res.list || res.records || res.rows || res.data || [] tableData.value = Array.isArray(list) ? list : [] pageInfo.value.total = res.total ?? tableData.value.length emit('load-success', res) } catch (error) { emit('load-error', error) } finally { loading.value = false } } const handlePageChange = (page) => { pageInfo.value.page = page fetchData() } const handleSizeChange = (size) => { pageInfo.value.pageSize = size pageInfo.value.page = 1 fetchData() } const handleSelectionChange = (rows) => { selectedRows.value = rows emit('selection-change', rows) } const handleRowClick = (row, column, event) => { emit('row-click', row, column, event) } const refresh = () => { pageInfo.value.page = 1 fetchData() } const reload = () => { fetchData() } onMounted(() => { if (props.immediate) { fetchData() } }) watch( () => props.queryParams, () => { refresh() }, { deep: true } ) defineExpose({ refresh, reload, getSelectedRows: () => selectedRows.value, getTableData: () => tableData.value }) </script>

脚本部分有几个工程问题需要在代码里提前处理掉，避免线上踩坑。

返回数据解析这里做了一层兼容：res.list || res.records || res.rows || res.data。不同后端团队返回字段不一样，有返回 records 的、有返回 rows 的，组件内部做兼容能减少接新项目时的改动量。但这里要谨慎处理 total，后端返回 total 时用 total，没有 total 时用当前数组长度兜底，这只能保证组件不报错，真实总数还是要以接口为准。

watch queryParams 用了 deep 监听。这意味着父组件修改 queryParams 的某个字段会自动触发刷新，不用手动调用 refresh。这个能力好用，但有个大坑：如果父组件在搜索回调里同时修改 queryParams 又手动调用了 refresh，就会触发两次请求。后面搜索表单联动部分我会详细说这个问题的解法。

expose 出来的 refresh 是"重置到第一页再请求"，reload 是"保持当前页重新请求"。这两个方法语义不同，比如删除当前页最后一条数据后，应该先判断当前页是否只剩这一条，是则页码减一再刷新，否则直接 reload。这个逻辑写在业务页面里更合理，所以组件只提供原始能力。

6. 搜索表单与表格联动

列表页几乎都有搜索功能。搜索表单和 BaseTable 的联动方式有两种，先看推荐方案。

6.1 推荐方案：queryParams 驱动

父组件维护一个响应式 searchParams，通过 queryParams 传给 BaseTable，组件内部 deep watch 到变化后自动刷新。

<template> <div> <div class="search-bar"> <el-input v-model="searchParams.keyword" placeholder="请输入用户名" clearable /> <el-select v-model="searchParams.status" placeholder="状态" clearable> <el-option label="启用" :value="1" /> <el-option label="停用" :value="0" /> </el-select> <el-button type="primary" @click="handleSearch">查询</el-button> <el-button @click="handleReset">重置</el-button> </div> <base-table ref="tableRef" :columns="columns" :api="fetchUserList" :query-params="searchParams" show-selection > <template #status="{ row }"> <el-tag :type="row.status === 1 ? 'success' : 'info'"> {{ row.status === 1 ? '启用' : '停用' }} </el-tag> </template> <template #action="{ row }"> <el-button link type="primary" @click="handleEdit(row)">编辑</el-button> <el-button link type="danger" @click="handleDelete(row)">删除</el-button> </template> </base-table> </div> </template>

脚本部分：

<script setup> import { ref } from 'vue' const tableRef = ref() const searchParams = ref({}) const handleSearch = () => { // 不在这里手动调用 tableRef.value.refresh() // BaseTable 内部已经 watch 到 queryParams 变化，会自动刷新 tableRef.value.refresh() } const handleReset = () => { searchParams.value = {} } </script>

上面这个示例其实暴露了那个坑：handleSearch 里既修改了 searchParams 又会触发 watch，页面里如果再调 refresh 就是双重请求。写代码时必须二选一。

我的建议是：如果 BaseTable 内部已经做了 deep watch，业务页面就不要再调 refresh，只负责修改 searchParams。但 deep watch 也有性能开销，如果 searchParams 对象特别大，每次修改都会触发深度遍历。

更可控的做法是在组件里去掉 deep watch，完全由父组件手动控制刷新时机：

<script setup> // BaseTable 内部不再 watch queryParams // 父组件搜索时手动调用 refresh const handleSearch = () => { searchParams.value = { ...formData } tableRef.value.refresh() } </script>

两种方案各有取舍。自动刷新的优点是父组件代码少，缺点是双请求的坑需要团队约定；手动刷新的优点是行为显式、可控，缺点是容易忘记调用。实际项目里我更推荐手动刷新，因为请求时机这件事越明确越不容易出错。如果团队约定用自动刷新，那就在组件 README 里明确写清楚"修改 queryParams 会自动请求，禁止再手动调用 refresh"。

6.2 搜索表单组件化

搜索表单本身也值得做轻量封装，但不要和 BaseTable 耦合太深。搜索表单的字段、校验规则、布局差异很大，强行塞进表格组件只会让组件变得臃肿。建议搜索表单单独维护，和 BaseTable 通过 queryParams 通信。

表单重置时要注意时间范围字段。如果用了 el-date-picker 的 daterange，提交时要转换成startDate和endDate两个字段，转换逻辑可以放在单独的工具函数里：

const formatSearchParams = (form) => { const { dateRange, ...rest } = form if (dateRange && dateRange.length === 2) { return { ...rest, startDate: dateRange[0], endDate: dateRange[1] } } return rest }

这个函数建议放在业务页面目录里，属于业务逻辑，不该进公共组件。

7. 批量操作与工具栏扩展

管理后台的列表页离不开批量操作。BaseTable 通过 showSelection 开启多选列，通过 toolbar 插槽把选中行传给父组件。

7.1 批量删除示例

<template> <base-table ref="tableRef" :columns="columns" :api="fetchUserList" show-selection row-key="id" > <template #toolbar="{ selectedRows }"> <el-button type="danger" plain :disabled="selectedRows.length === 0" @click="handleBatchDelete(selectedRows)" > 批量删除 </el-button> <el-button type="primary" @click="handleAdd">新增用户</el-button> </template> </base-table> </template> <script setup> import { ElMessage, ElMessageBox } from 'element-plus' import { fetchUserList, batchDeleteUser } from './api' const tableRef = ref() const handleBatchDelete = async (rows) => { const ids = rows.map((row) => row.id) await ElMessageBox.confirm(`确认删除选中的 ${ids.length} 条数据？`, '提示', { type: 'warning' }) await batchDeleteUser(ids) ElMessage.success('删除成功') tableRef.value.refresh() } </script>

这个例子里 row-key 是必须的。多选列开启后，如果不设置 row-key，翻页时选中状态会丢失。Element Plus 的多选记忆依赖 row-key，同时 el-table-column 要加上reserve-selection="true"，这个属性在 BaseTable 模板里已经写好了。

批量操作要注意的细节是权限控制。toolbar 插槽里可以包一层权限判断组件，比如 v-permission 指令，没有权限就不渲染按钮。不要把权限逻辑写进 BaseTable，那是业务层的职责。

7.2 动态列配置

动态列的意思是列配置可以根据角色、页面状态、用户设置动态生成。列配置通常是从接口拿到的，也可能是前端根据权限计算的。

<script setup> import { computed } from 'vue' const props = defineProps({ showScore: { type: Boolean, default: false }, role: { type: String, default: 'admin' } }) const columns = computed(() => { const cols = [ { prop: 'name', label: '用户名', minWidth: 140 }, { prop: 'email', label: '邮箱', minWidth: 180, ellipsis: true } ] if (props.showScore) { cols.push({ prop: 'score', label: '积分', width: 100, align: 'center' }) } if (props.role === 'admin') { cols.push({ prop: 'department', label: '部门', width: 120 }) } return cols }) const actionColumn = { prop: 'action', label: '操作', width: 160, fixed: 'right', slot: 'action' } </script>

注意操作列的处理。操作列不依赖接口数据，直接放在 columns 里配置使用 action 插槽即可，BaseTable 的插槽机制会把它渲染出来。操作列建议固定在最右侧，用fixed: 'right'，列宽按按钮数量和文案长度估算，一般在 140 到 200 之间。

动态列有一个需要协调的指标：列宽。数据量大的时候，所有列都用固定宽度会导致小屏幕下横向滚动条件很差；全部用 min-width 又会让表格在宽屏下拉伸得很难看。实践上，文本短且固定的列用 width，文本可能很长的列用 min-width 加 show-overflow-tooltip，操作列一律用固定 width。

8. 性能优化与渲染注意事项

表格是列表页性能消耗的重灾区，封装组件的时候就要把性能问题考虑进去。

8.1 优先使用服务端分页

中后台列表页的数据量通常较大，一次性把几千条数据拉到前端不仅慢，而且 DOM 渲染会很卡。默认就应该走服务端分页，也就是 BaseTable 每次请求都带 page 和 pageSize。前端分页只适合数据量小、接口一次性返回全部数据的场景。

服务端分页的另一个好处是排序也可以交给后端。列配置里sortable: 'custom'开启服务端排序，监听 el-table 的 sort-change 事件，把排序字段和排序方式拼进请求参数即可。BaseTable 目前没有内置 sort-change，属于可以扩展的方向，有需要的团队可以在组件里加一个 sortable 参数，把排序信息通过@sort-change透传出来，由父组件决定如何拼接参数。

8.2 控制单元格渲染成本

表格中每一个单元格都是一个组件实例，列多、数据多的时候，渲染成本会成倍上升。以下几条优化手段按性价比排序：

1. 减少不必要的插槽。能用默认渲染就不要写插槽，每个插槽都会多一层 vnode 解析。
2. 避免整列使用复杂组件。比如状态列，优先用 el-tag 而不是自定义组件。
3. 列宽优先用 min-width，减少横向滚动时的重排压力。
4. show-overflow-tooltip 会用 tooltip 包裹单元格，列特别多的时候工具提示实例数量很大，只在有长文本需求的列开启。
5. 固定列（fixed）会额外渲染一层表格，能用尽量少用，一般只固定操作列。

8.3 大数据量下的虚拟滚动

如果业务确实需要一次性展示大量行数据，比如导出预览或者全量展示，可以考虑虚拟滚动。Element Plus 的 el-table 在 2.4 版本之后对虚拟表格有实验性支持，也可以引入基于 el-table 的社区虚拟表格方案，或者换成 Ant Design Vue 的虚拟表格。

虚拟滚动不是银弹，它牺牲了部分能力换渲染性能。开启虚拟滚动后，行高必须是固定的，表格的自动高度、列宽自适应、复杂插槽都会受到限制。判断标准很简单：一屏数据超过几百行再考虑虚拟滚动，普通分页列表完全不需要。

8.4 避免深层监听带来的性能损耗

BaseTable 内部对 queryParams 做了 deep watch。如果 queryParams 里有大型对象（比如富文本内容、大数组），每次修改都会造成深度遍历。改进思路是组件只做浅监听，要求父组件在数据变化时传入新的对象引用，或者干脆去掉自动监听改为手动 refresh。我在第 6 节推荐手动刷新，原因就在这，性能更可控，行为也更显式。

9. 常见问题与排查方法

把封装表格组件过程中的高频问题整理成一张排查表，遇到问题先查这张表。

几个重点排查项展开说一下。

插槽不渲染这个问题的坑在于，BaseTable 用col.slot || col.prop动态决定插槽名。如果父组件里写了#customName，但列配置里没有对应的 slot 字段，组件默认走 prop 名插槽，页面自然显示默认 span。排查时先看列配置里的 prop 和 slot，再对照父组件模板里的插槽名。

多选翻页丢失的问题，除了 row-key 之外还要注意数据唯一性。row-key 对应的字段必须是每条记录的唯一值，如果后端返回的 id 在同一页数据里不唯一，选中记忆依然会混乱。

批量删除后列表不刷新，最常见的错误是删除成功后调用了 reload 而不是 refresh。当前页删光了数据，reload 会停留在空页面，这时候应该把页码重置到第一页或者做页码减一处理。

10. 最佳实践与团队规范

表格组件封装做完只是第一步，让团队统一使用、持续迭代才是目的。这里给几条可落地的团队实践建议。

10.1 统一接口返回结构

BaseTable 在内部做了一层字段兼容，但它只是兜底，不能替代接口规范。团队应该和后端约定统一的列表接口返回结构，比如：

{ "code": 0, "message": "success", "data": { "list": [ { "id": 1, "name": "张三", "status": 1 } ], "total": 128, "page": 1, "pageSize": 10 } }

axios 响应拦截器统一解包 code 和 data，业务层拿到的就是 data 对象。BaseTable 内部再按res.list和res.total解析，这样所有列表页的解析逻辑就完全一致了。

10.2 列配置独立、注释清晰

columns.ts 是团队最容易忽略维护的地方。列配置文件里每列都要写清楚字段来源和展示逻辑，特别是字典字段。比如 status 列的注释要写明"1-启用，2-停用，3-封禁"，这样后续接手的人不用翻接口文档。

字典字段的展示建议做成全局字典翻译组件，比如 DictTag。BaseTable 不限制列配置里透传的内容，dict 字段由业务页面在插槽里处理，保持组件纯净。

10.3 用 TypeScript 泛型提升体验

如果项目使用 TypeScript，建议给 BaseTable 增加泛型支持。组件接收一个泛型 T，表示行数据类型，这样插槽和作用域插槽里的 row 都能获得类型提示。复杂类型定义可以写在 types.ts 里：

export interface TableColumn { prop: string label: string width?: number | string minWidth?: number | string fixed?: 'left' | 'right' | boolean sortable?: boolean | 'custom' align?: 'left' | 'center' | 'right' ellipsis?: boolean slot?: string } export interface PageResult<T> { list: T[] total: number } export type TableApi<T> = (params: Record<string, any>) => Promise<PageResult<T>>

父页面使用时的收益非常明显：<base-table :columns="columns" :api="fetchUserList" />里的插槽#status="{ row }"能自动推断 row 是用户类型，避免手写 any。

10.4 写 demo 页和文档

组件放在项目里几个月后就会有人提问"这个参数怎么用"。与其反复口头解释，不如在项目里建一个 component-demo 页面，把 BaseTable 的常见用法全部列出来：基础表格、查询联动、批量操作、动态列、插槽自定义、刷新方法调用。这个 demo 页同时也是组件的回归测试用例，改动组件后跑一遍 demo 就能发现回归问题。

README 文档不需要很长，但必须写清楚 props 表、插槽表、expose 方法表，以及一个最小可运行代码示例。

10.5 不要过度设计

刚开始封装时，只要满足当前业务的 80% 需求就够了。不需要一开始就做列拖拽、列显隐、列宽记忆、导出一体化。这些能力可以后续通过协议扩展，组件加参数是增量兼容，拆掉一个设计不好的参数却要动很多调用方。

比较好的迭代节奏是：第一个月只做数据请求、分页、多选、插槽，等团队用顺了，再根据真实需求逐步加能力。

总结与下一步

表格组件封装的本质，是把业务列表页里重复出现的"请求数据、分页、loading、选择、刷新"这些横切逻辑抽出来，让页面只保留差异化的展示和操作。我建议先从 BaseTable 最小版本开始：props 只留 columns、api、queryParams、showPagination、showSelection，插槽只做 toolbar 和单元格插槽，expose 暴露 refresh 和 reload。拿项目里第一个列表页做试点，跑通之后，第二个页面开始复制粘贴的成本就会降下来。

最容易踩的坑有两个：一个是 queryParams 自动刷新和手动 refresh 造成双请求，另一个是返回值字段解析不一致导致列表空白。这两点提前在 README 里写清楚，团队就不会反复踩。

下一步可以考虑把搜索表单也抽象成 SearchBar 组件，和 BaseTable 组合成 SearchPage 页面容器。但组合时务必保持低耦合，搜索表单用 queryParams 和表格通信，不要强行合并成一个巨型组件。前端组件封装的长期价值在于稳定和可预测，而不是功能大而全，这个原则对表格组件尤其适用。