管理后台的项目做多了之后你会发现一个特别有意思的现象不管业务是订单、用户、商品、文章还是权限列表页的骨架几乎一模一样——顶部的筛选条件、中间的表格和操作栏、底部的分页再加一个批量删除或者批量导出。我刚工作那会儿每接到一个新模块第一反应就是复制上一个页面的代码改改字段、换换接口半天能出一个能跑的页面。但几个月后噩梦就来了有的页面筛选后没有重置页码有的页面全选只选中了当前页有的页面排序状态一刷新就丢了还有的页面表格和分页的状态散落在各个组件里改一个功能要翻好几个文件。后来我下定决心把这套逻辑统一拿出来用 Vue3 的组合式函数和泛型组件重新做了一遍封装也就是这篇文章要聊的内容——列表与表格的分页、筛选、排序、批量操作和 Hook 封装全部基于 Vue3 的核心语法和组件模式。这篇内容适合正在用 Vue3 写后台管理系统、已经对 Composition API 有基本了解、想把手头重复的列表代码整理成可复用模块的开发者也适合那些面试前想系统梳理表格场景核心点的人。我会从需求拆解讲起把每一步设计背后的理由、踩过的坑、以及最终的代码形态都放出来你完全可以照着这套思路去重构自己的项目。1. 表格列表需求的共性拆解每个列表页都在重复什么先把一个标准后台列表页的痛点拆开看。表面上每个页面都不同但抽掉业务字段之后所有页面共享的状态结构和交互逻辑几乎是一样的。1.1 状态层面的共性几乎所有列表页都需要维护以下这组状态查询参数用户在筛选区域填的输入框、下拉框、日期范围等条件通常会组装成一个对象传给后端分页信息当前页码、每页条数、总条数表格数据当前页要展示的记录数组加载状态首次加载、筛选后加载、分页切换时的 loading 状态选中状态勾选了哪些行以及更复杂的跨页是否保留选中排序状态当前排序的字段和排序方向有些系统还支持多字段排序。在没有封装的情况下每个页面都会用 ref 把这些状态声明一遍然后在 methods 或者普通函数里写一模一样的数据获取逻辑。这不仅是代码重复的问题更大的隐患是行为不一致——A 页面筛选后记得回到第一页B 页面忘了产品验收的时候就会发现同样的操作在不同页面表现不同这比代码冗余更让人头疼。1.2 交互层面的共性除了状态交互流程也是一套固定套路页面加载时自动拉取第一页数据点击查询/搜索时带着最新条件回到第一页重新拉取点击重置时清空条件并回到第一页拉取切换页码或改变每页条数时带着现有条件拉取新数据点击表头排序时带着排序字段和方向重新拉取勾选行、全选、批量操作后刷新列表或删除选中项。其中第 2、3 条是最容易出问题的。很多新手会把查询参数和分页参数分开管理一旦筛选条件发生变化页码还停留在上一次的位置。比如你在第 5 页输入了一个关键词筛选结果接口返回的是新条件下的第 5 页——如果这个关键词匹配的总数据量只有两页你就会看到一个空列表而根本问题只是页码没有重置。正确的做法是查询条件的任何变化都要让分页器回到第一页。这条规则听着简单但在封装设计时需要考虑清楚触发时机因为我们既不能每次输入框一变就触发请求也不能在点击查询之前就偷偷改了页码导致用户困惑。通常的做法是维护两个对象一个用于绑定表单formModel一个用于真正发送请求的查询参数queryParams。点击查询时才把 formModel 深拷贝给 queryParams同时把 pageNo 重置为 1再执行拉取动作。这样就保证了输入过程中修改条件是不会骚扰接口的。提示不要直接在表单的 change 事件里去重置页码并请求除非你的筛选是即时搜索交互。后台管理的标准的查询-重置模式下用户期望自己点击查询按钮后才生效。1.3 为什么需要统一封装当我数了一下自己负责的模块有 30 多个列表页面时我意识到继续复制粘贴只会让维护成本指数上升。统一的封装可以带来三个直观的好处行为一致筛选、重置、分页、排序的触发逻辑由同一套代码管理用户不管在哪个页面操作体验都一样心智负担小新页面只需要配置请求函数、表格列、表单字段不需要关心内部状态流转修改成本低比如后端要求所有列表接口新增一个是否需要返回总数的参数或者统一的错误处理逻辑变更只需要改一处。这个先把共性抽出来的过程其实也是 Vue3 组合式函数最典型的应用场景。接下来我按分页、筛选排序、批量操作、Hook 封装、泛型组件这几个部分逐步拆开说。2. 分页逻辑的设计取舍前端分页与服务端分页的边界分页看着是最简单的功能实际上只要多问几个如果就能发现不少设计点。先说两种分页模式再说我的选择标准。2.1 前端分页的适用场景前端分页指的是后端一次性把所有数据返回前端在内存里做 slice 切页。这个方案只适合两种场景数据量上限明确且很小比如一个用户下的标签列表、配置项列表总量可能就几十条后端接口不支持分页参数且没有改造成本。前端分页的好处是切换页码无需重新请求接口体验上极快。但它的缺点也很致命数据量一大接口响应变慢、浏览器内存吃紧。我之前接手过一个旧系统列表接口每次返回全量数据最多的时候上万条记录全部渲染到 DOM 上页面卡到滚动都掉帧。后续改造第一步就是让后端支持 LIMIT/OFFSET然后把分页模式切换成服务端分页。所以我的建议是对于任何潜在数据量超过几百条的业务列表直接按服务端分页设计前期多写一点代码能避免后期大面积返工。2.2 服务端分页的核心状态流服务端分页模式下前端要维护的核心状态就是pageNo和pageSize以及后端返回的total。关键点在于调用接口的参数必须同时包含查询条件和分页参数缺一不可。这里有一个很容易写的反模式我反复在一些项目里见到// 反模式把分页参数存在组件内部 ref 里请求时单独读取 const pageNo ref(1) const pageSize ref(20) function loadData() { api.list({ ...filterForm.value, pageNo: pageNo.value, pageSize: pageSize.value }) }这种写法能跑但你会在多个函数里反复手动组合这两个来源的参数并且后续做 Hook 封装时要多传两个 ref 进去接口函数签名会非常啰嗦。更好的方式是把分页参数和查询条件放进同一个状态对象里统一管理。我们后面 Hook 封装时这个状态对象就是整个表格逻辑的单数据源。2.3 每页条数变化的处理细节除了页码切换还有一个容易被忽略的细节是 pageSize 变化。假设用户当前在第 10 页每页 20 条现在把每页条数改成 50如果仍然停留在第 10 页那么实际展示的数据区间就会跳变用户很难理解发生了什么。行业通用的交互方案有两种一种是修改 pageSize 后重置 pageNo 为 1另一种是用一个换算公式尽量保持用户看到的起始位置不变比如新页码 floor((旧页码 - 1) * 旧pageSize / 新pageSize) 1。第一种方案简单粗暴大多数后台管理系统都用这个第二种更精细但只有像 Grove 这类数据查看器才会刻意设计。我建议后台管理直接用方案一pageSize 变化时 pageNo 归 1。原因是业务列表很少需要精确保持滚动位置用户改变每页条数通常就是想换个更大的视图从第一页开始看是完全合理的行为。2.4 后端分页接口的约定问题前端封装做得再好如果后端接口的分页参数命名不统一照样要出问题。有的接口用page、limit有的用pageNum、pageSize有的用offset、rows。我在做 Hook 封装时会同时支持两种最常见风格并在封装的请求函数里做一层适配。还有一种更隐蔽的情况后端明明要的是 0 起始的下标前端给的是 1 起始的页码。比如点击第 1 页前端传pageNo: 1后端内部计算出offset (pageNo - 1) * pageSize这没问题但有些后端懒得算要求前端直接传offset: 0那就是(1-1)*200。这种约定差异如果不在请求函数里抹平换一个接口就能踩坑。我封装时会固定暴露pageNo和pageSize给业务页面用内部再去适配后端参数。提示设计接口时优先统一约定为pageNo从 1 开始和pageSize前端代码语义更清晰也符合多数 UI 组件库的页码概念。3. 筛选、排序与表格状态的联动一个值得单独说道的细节筛选和排序单独拎出来每个都简单但它们和分页、请求之间的联动关系才是最考验代码组织能力的地方。3.1 查询参数与表单状态的解耦前面提过维护一个绑定表单的formModel和一个真正发送请求的queryParams这是第一步。但接下来还有几个细节需要注意。一是重置操作的粒度。常见的重置有两种一种是把表单重置为空白初始值另一种是重置为首次进入页面时的默认值。不要小看这个区别。有些列表默认带一个状态条件比如只显示未处理用户改成全部后点击重置大多数产品预期是回到只显示未处理这个业务默认值而不是把下拉框清空。所以设计时不要写死formModel {}而要把初始默认值对象保存起来重置时使用它。二是避免表单校验打断请求。有些筛选表单使用了表单校验比如日期范围必填。正确做法是在点击查询时先执行校验校验通过后再组装 queryParams 并请求。但如果封装层面把请求逻辑写在 Hook 里表单校验写在组件里就需要通过返回值或者回调来保证执行顺序。我在封装时会让search函数返回一个Promise组件在调用前自行完成校验校验不通过就return不调用search这样职责边界很清晰。三是深拷贝的必要性。表单对象如果用reactive声明直接赋值给 queryParams会带着响应式引用关系。后续修改表单时就可能意外改动 queryParams导致还没点查询数据却已经被过滤了这种幽灵 bug。所以组装 queryParams 时务必JSON.parse(JSON.stringify(...))或使用工具函数深拷贝。这一步在面试里也常被问到属于看着不起眼但影响正确性的细节。3.2 表格排序的监听与参数传递Element Plus 的el-table提供了sort-change事件但很多人在监听处理后会把排序方向和字段名存成一个固定结构导致和不同后端的字段约定对不上。先看 Element Plus 的事件参数sort-change会回调{ column, prop, order }其中order只有三个值ascending、descending、null。null表示取消排序。而后端接口通常希望收到sortField: 字段名和sortOrder: asc | desc如果不做转换就直接传会出现传ascending这种前端独有的值。我在封装里的处理方式是把order映射成asc/desc/并在sort-change回调里赋值给 queryParams同时当成条件变化触发页码重置和请求。还有一个细节是默认排序——如果列表首次加载就需要按某个字段排序不要依赖el-table的default-sort属性因为它只影响表格展示不会主动触发事件。正确的做法是在 queryParams 的初始值里直接带上排序字段。3.3 查询条件中包含日期范围的处理后台列表特别常见的日期范围筛选前端控件通常是[startTime, endTime]这种数组但接口字段往往要拆成两个独立的字段传。这个转换放哪里做我的习惯是在组装 queryParams 时统一平铺。不要在表单绑定阶段就拆因为拆完数组之后回填就会出现麻烦下拉回显时还得组装回去。而是在buildParams这个纯函数里做转换这样前端表单结构和后端接口字段结构解耦后续接口字段改名时只需要改这一个函数。3.4 筛选与排序的共同重置策略总结筛选、排序、分页的联动策略我总结成一张简单的规则表方便你照着设计自己的封装触发动作是否重置页码是否触发请求说明点击查询是是把表单值同步到 queryParams点击重置是是用初始默认值覆盖表单页码切换否是只改 pageNopageSize 变化是是回到第一页排序变化是是排序字段加入 queryParams表单输入中否否不实时请求这张表就是后面 Hook 封装的行为基准。4. 批量操作与跨页选中最容易被忽视的坑批量操作包括批量删除、批量导出、批量审批核心难点其实不在操作本身而在全选的语义。4.1 el-table 全选的两种语义Element Plus 的表格选择列默认行为是当数据刷新后已勾选状态会保留在组件内部。但如果你点击了表头的全选复选框它只能选中当前页所有行数据切换到另一页后之前勾选的行虽然没有清空但你再点全选时它会基于当前页数据重新计算很容易出现第一页全选后翻到第二页再点全选结果只选中了第二页甚至取消了一些之前的选中这种奇怪体验。问题的本质在于用户心里的全选到底是选中当前页全部还是选中所有满足条件的数据。这就是产品逻辑的分叉点。4.2 只做当前页全选的简单方案如果业务场景明确不需要跨页选择比如批量操作在翻页后要保持选中行仍然存在但用户一般不指望全量操作那么你可以简单地维护一个selectedRows数组监听selection-change事件把它赋值给它就行。删除成功后清空数组。这个方案实现成本低但要确保翻页后已勾选行还在——因为 el-table 默认会对新渲染的行保留选中状态只要行的row-key属性配置正确翻页后刷新数据之前选中的行依然会保持勾选。这里有个关键点不配置row-key时刷新数据会导致选中状态丢失。给el-table加上row-keyid选中的行才能稳定保留。4.3 跨页全选与半选的处理如果你的业务确实需要跨页全选那就要引入更严谨的选中管理。我采用的方案是不直接依赖selection-change作为唯一数据源而是自己维护一个选中的 ID 集合。思路如下用ref维护selectedRowKeys这个Set行勾选变化时用toggleRowSelection/selection-change事件去同步selectedRowKeys表头全选勾选时把当前页所有行的 id 加入集合如果全选被取消把当前页所有行 id 从集合中移除翻页加载新数据后用row-key和selectedRowKeys反推哪些行应处于勾选状态通过toggleRowSelection(row, true)重新设置。核心难点在第 3、4 步。直接监听selection-change再赋值会覆盖其它页的选中状态正确做法是让selection-change只负责把界面的勾选结果同步到集合而全选按钮的全选当前页/取消当前页逻辑单独写处理函数。考虑到实现复杂度实际开发里我建议保守一点除非产品明确要求否则默认只做当前页全选 翻页保留已选的模型。绝大多数后台业务中用户的批量操作对象只是当前看到的这一批数据跨页全选有点像全选后我又筛了个条件再全选状态管理复杂度会指数上升操作结果也未必符合用户预期。4.4 批量删除完成后的联动刷新批量删除成功之后有一个细节很容易忽略删除后当前页可能只剩空数据或者删掉的是最后一页的最后几条此时应该把页码往前调整。否则用户会看到一个空白页误以为操作失败了。我在封装里提供了一个reload函数它内部会判断如果当前页数据删除后为空且 pageNo 大于 1就先执行pageNo--再触发请求。这个逻辑同样适用于单条删除。还有一个细节是批量操作进行中要锁住按钮防止重复提交。我给按钮绑定的loading状态和表格加载状态是分开的因为批量操作的 loading 只作用于那个按钮不应该让整个表格重载否则用户会看到表格内容闪烁。提示批量操作的二次确认弹窗里最好展示已选 X 项的数量并说明是全选了当前页还是全部页。这个数量直接用selectedRows.length即可如果跨页选中的话用集合 size。5. 用 Hook 抽取表格逻辑useTable 组合式函数落地前面聊了一大堆设计原则现在到了代码落地的环节。我会以一个综合了分页、筛选、排序、批量选择和请求调用的useTable为例展示 Vue3 组合式函数怎么把这套逻辑真正收敛起来。5.1 Hook 的输入与输出设计在动手写之前先明确这个 Hook 要接收什么、返回什么。输入fetchApi一个接收查询参数、返回Promise{ list, total }的函数initParams初始查询参数包括筛选默认值、排序默认值、分页默认值options可选配置比如是否立即加载、请求失败是否提示、rowKey 字段名等。输出数据与加载状态tableData、loading、total分页状态与操作pageNo、pageSize、pageChange、sizeChange排序处理handleSortChange筛选操作search、reset选择相关selectedRows、selectedRowKeys、clearSelection底层函数getList、reload。这样设计的好处是业务组件不需要关心请求是怎么发出去的也不需要自己声明一堆 ref 再用 watcher 串联。所有联动逻辑在 Hook 内部完成组件里只需要调函数。5.2 useTable 核心代码实现先看一个简化但完整的实现后续再讲关键点import { ref, reactive, onMounted } from vue export function useTable(fetchApi, initParams {}, options {}) { const { immediate true, rowKey id } options // 用 reactive 统一管理查询参数避免手动拼接 const queryParams reactive({ pageNo: 1, pageSize: 10, ...initParams }) // 保存初始默认值供重置时使用 const defaultParams JSON.parse(JSON.stringify(queryParams)) const tableData ref([]) const total ref(0) const loading ref(false) // 选中状态 const selectedRows ref([]) const selectedRowKeys new Set() // 请求核心函数 async function getList() { loading.value true try { const params JSON.parse(JSON.stringify(queryParams)) const res await fetchApi(params) tableData.value res.list ?? [] total.value res.total ?? 0 } finally { loading.value false } } // 页码切换 function pageChange(page) { queryParams.pageNo page getList() } // 每页条数变化 function sizeChange(size) { queryParams.pageSize size queryParams.pageNo 1 getList() } // 点击查询用外部传入的最新筛选值覆盖 queryParams function search(values) { Object.keys(values || {}).forEach((key) { queryParams[key] values[key] }) queryParams.pageNo 1 getList() } // 重置回到初始默认值 function reset() { Object.keys(defaultParams).forEach((key) { if (key ! pageNo key ! pageSize) { queryParams[key] defaultParams[key] } }) queryParams.pageNo 1 getList() } // 排序处理 function handleSortChange({ prop, order }) { if (!prop) { delete queryParams.sortField delete queryParams.sortOrder } else { queryParams.sortField prop queryParams.sortOrder order ascending ? asc : order descending ? desc : } queryParams.pageNo 1 getList() } // 同步选中集合 function syncSelection(rows) { selectedRows.value rows selectedRowKeys.clear() rows.forEach((row) selectedRowKeys.add(row[rowKey])) } // 当前页全选/取消 function handleSelectAll(rows, isSelect) { rows.forEach((row) { if (isSelect) { selectedRowKeys.add(row[rowKey]) } else { selectedRowKeys.delete(row[rowKey]) } }) // 这里需要反向同步 el-table 的选中状态 } // 清空选中 function clearSelection() { selectedRows.value [] selectedRowKeys.clear() } function reload() { if (tableData.value.length 0 queryParams.pageNo 1) { queryParams.pageNo - 1 } getList() } if (immediate) { onMounted(getList) } return { queryParams, tableData, total, loading, selectedRows, selectedRowKeys, pageChange, sizeChange, search, reset, handleSortChange, syncSelection, handleSelectAll, clearSelection, getList, reload } }这段代码里其实还有几个值得展开讲的地方。5.3 为什么用 reactive 而不是多个 ref在 Hook 内部我选择把 pageNo、pageSize、sortField、sortOrder、筛选字段全部放在一个reactive对象里。这样搜索引擎参数时只需要一次性深拷贝这个对象不会漏字段也不会出现页面里改了 A 条件请求里只有一个旧值这种错位。有些开发者习惯把 pageNo 和 pageSize 单独抽成 ref理由是分页器需要显式绑定。实际上 Element Plus 的分页器可以直接绑定queryParams.pageNo响应式嵌套对象在 Vue3 里是完整支持的所以没有维护成本问题。一个状态对象打天下比多个 ref 再加 computed 组装心智负担更小。5.4 search 和 reset 的参数传递方式刚才代码里search(values)接收一个外部传入的对象把它的字段覆盖到 queryParams 上。这要求组件的表单对象和 queryParams 里的字段名一致。有人会问为什么不直接在 Hook 里用 reactive 创建 formModel我试过在 Hook 里创建 formModel但发现表单的校验规则、字段类型和展示逻辑往往和页面强绑定强行塞进 Hook 会让 Hook 变得很重。所以我的取舍是Hook 只管请求参数表单由组件自己管只在点击查询时把表单值传给search。reset则相反——因为 Hook 内部保存了defaultParams所以重置时组件只需要调用reset()并把自己的 formModel 恢复成默认值。两者配合时要注意重置后组件里的表单回显值也必须更新最好在声明 formModel 时就把默认值定义成一个独立常量组件和 Hook 都引用它。5.5 封装后的组件侧使用示例下面是一个业务组件使用useTable的完整骨架script setup import { reactive } from vue import { useTable } from /hooks/useTable import { fetchUserList, deleteUsers } from /api/user // 表单默认值组件侧维护 const defaultForm { keyword: , status: , dateRange: [] } const formModel reactive({ ...defaultForm }) const { queryParams, tableData, total, loading, selectedRows, pageChange, sizeChange, search, reset, handleSortChange, syncSelection, clearSelection, getList } useTable(fetchUserList, { ...defaultForm, sortField: createTime, sortOrder: desc }, { rowKey: id }) function handleSearch() { search({ ...formModel }) } function handleReset() { Object.assign(formModel, defaultForm) reset() } function handleBatchDelete() { // 调删除接口后 reload } /script页面里表格部分的模板代码就非常薄了el-table v-loadingloading :datatableData row-keyid selection-changesyncSelection sort-changehandleSortChange el-table-column typeselection width50 / !-- 业务列省略 -- /el-table el-pagination background layouttotal, sizes, prev, pager, next, jumper :totaltotal :page-sizequeryParams.pageSize :current-pagequeryParams.pageNo :page-sizes[10, 20, 50, 100] current-changepageChange size-changesizeChange /到这里一个页面里原来最啰嗦的 100 多行逻辑就收敛成了几十行业务配置而且每个页面的行为都一致了。6. 表格组件的泛型封装类型安全与可扩展性Hook 解决了逻辑复用但视图层还有个问题每个页面还是要写一遍几乎一样的el-table结构包括 loading、selection 列、空数据状态等。更进一步我们希望表格组件能对业务行数据类型做类型约束在写列配置时就享受到 IDE 的类型提示。这就轮到泛型组件登场了。6.1 泛型组件的基本形态Vue3 的script setup里定义泛型组件需要用defineProps配合generics选项。以 TypeScript 为例script setup langts genericsT extends { [key: string]: any } import type { TableColumn } from /types/table interface Props { columns: TableColumnT[] data: T[] loading?: boolean rowKey?: keyof T | string selectable?: boolean } definePropsProps() // 泛型事件向父组件抛出当前行类型 const emit defineEmits{ (e: row-click, row: T): void (e: selection-change, rows: T[]): void (e: sort-change, sortState: { prop: keyof T; order: asc | desc | }): void }() /script这样写之后在父组件使用UserTable :columnscolumns :datatableData :loadingloading row-keyid selection-changesyncSelection sort-changehandleSortChange /其中columns的类型由TableColumnT决定T 在父组件里是UserInfo接口所以列配置里写prop: userName时 IDE 会给出正确的字段提示字段名打错了会直接报红。这在项目大、字段多的时候特别有价值。6.2 列配置驱动的动态列渲染把列做成配置数组之后列本身还可以扩展很多能力比如是否需要排序、宽度、是否展示、是否支持操作列插槽。我常用的一种列类型定义是export interface TableColumnT { prop: keyof T string label: string width?: number | string minWidth?: number | string sortable?: boolean | custom formatter?: (row: T, value: any) string slots?: { default?: (row: T) VNode header?: () VNode } }formatter可以处理纯展示的格式化不需要额外写插槽需要复杂交互的列才用slots。这样大部分列表页的列都是纯配置项只有少数列需要自定义渲染组件内部的模板复杂度也控制在合理范围。6.3 表格组件与 Hook 的组合关系泛型表格组件负责渲染和事件抛出useTable负责状态和请求逻辑两者在页面组件里组合。最终形成的文件组织方式是这样的hooks/useTable.ts状态管理通用逻辑components/BaseTable.vue通用表格容器api/xxx.ts每个模块的接口函数views/xxx/index.vue页面组件只写表单配置、列配置、少量交互函数。有一次新来的同事接一个列表模块当天就完成了。我帮他看代码的时候想找他踩坑的地方翻了半天没找到——因为所有容易出问题的行为都在 Hook 里固定好了。那一刻我确实觉得这套封装值了。6.4 封装时要避免的过度设计说到最后我也得泼一盆冷水。表格封装很容易做过火。我见过有人把列配置、权限、字典翻译、导出、列宽拖拽、显隐列全部塞进一个超级表格组件结果组件光 props 就有二十多个维护成本反而比每个页面单独写还高。我的原则是两个凡是凡是超过 80% 页面都需要的才放进基础封装凡是只在少数页面出现的一律不放进基础封装需要时在页面里自己扩展。列宽拖拽、列显隐这种功能一两个页面需要就用表格的局部特效做所有页面都需要的基础场景才值得放进去。封装不是目标用最小的维护成本支撑最多的业务场景才是目标。7. 我踩过的几个坑和最终沉淀的经验最后聊一些代码之外的东西。这些是我在实际项目中踩过、也修复过的具体坑如果你正在做类似的封装大概率能提前避开。第一个坑是selection-change触发的时序问题。绑定selection-change之后在syncSelection里更新selectedRows但如果同时又在 Hook 内部调用了clearSelection()可能会因为清空行为触发一次selection-change回调导致上一次选中的数据被意外清掉。解决方案是用nextTick包裹清空操作或者调整清空逻辑的先后顺序先置空数据源再让表格解除选中。第二个坑是接口返回数据结构不一致。有的接口返回{ records: [], total: 100 }有的返回{ rows: [], count: 100 }更有一些老接口直接返回{ data: { list: [...] }, total: 0 }。如果 Hook 内部写死了res.list和res.total换个接口就崩。最终我在fetchApi的封装处做了一个统一的接口适配层不管后端怎么命名最终返回给useTable的都是{ list, total }结构。第三个坑是筛选区日期组件在重置时回显异常。defaultForm里日期范围是空数组组件里绑定了日期范围选择器重置时 Object.assign 把空数组赋值过去但 Element Plus 的日期选择器在值变更为空数组时如果绑定的类型是 null 不是 []会出现显示异常。这类组件库的边界问题只能在封装测试阶段多覆盖几种重置场景。第四个坑是排序与分页混在一起的接口参数污染。有一个页面在排序完成后翻页发现数据又变回未排序状态。查到最后是接口的排序参数只能跟分页参数同时传递但后端的实现里有 bug页码变化时没读排序参数。前端排查时一度以为是自己状态丢值最后只能让后端修复。这也提醒我排序状态必须和分页参数放在同一个 queryParams 对象里传递因为这个同传能减少双方约定不一致的概率。第五个坑是切换页面时旧页面的请求覆盖新页面。用户先在一个列表页发起了请求快速切换到另一个列表页如果第一个请求尚未返回它的响应可能会渲染到新页面组件上。解决方式是在组件销毁时取消未完成的请求或者在 fetch 函数里为请求加上类似 AbortController 的取消机制。这个点在我最初封装时完全没考虑直到线上出现列表数据闪成上一个页面数据的脏数据现象才警觉。除了具体的坑我再分享几条沉淀下来的使用建议。第一不要为所有页面强行套同一个分页器。有的页面是列表 详情跳转逻辑有的页面是树表 懒加载我会在 BaseTable 里允许pagination属性传入 false这些特殊页面就不显示分页器逻辑上照常走 useTable 的 getList。第二筛选表单的字段命名要和后端字段保持一致避免在前端组件层做大量字段名翻译。比如后端叫createdAt前端表单就老老实实叫createdAt不要叫createTime否则每次请求都要写映射函数纯属给自己加负担。第三排序的默认可视化状态需要通过 el-table 的default-sort声明。因为初次进入页面时queryParams 里已经带了默认排序但表格表头的排序图标不会自动点亮。我得在页面里给 el-table 加 default-sort 属性让视觉状态和后端实际排序逻辑一致。第四测试用例可以围绕分页边界写。我在封装后写了几个比较关键的测试场景第一页筛选、最后一页删到空、pageSize 从大改小、跨页选中后再翻页、排序切换后页码重置。这些场景覆盖了绝大部分开发中会遇到的回归问题每次改封装代码都要跑一遍。如果你现在正准备把项目里的列表页做一轮重构我的建议是别一上来就写代码先在纸上把上文的行为规则表列清楚和产品确认清楚全选语义再动手封装。实现本身并不复杂真正容易出问题的都是这类看不见的交互边界。一套好的封装用起来之后你会明显感觉到新页面开发的速度和稳定性都上了一个台阶后续再遇到类似场景时专注点也从怎么让它能跑变成了业务逻辑怎么表达得更好。 
长河君 · 2026/9/30 8:25:18 · 阅读 1.2k Vue3后台管理表格列表封装：分页筛选排序与批量操作Hook设计
管理后台的项目做多了之后你会发现一个特别有意思的现象不管业务是订单、用户、商品、文章还是权限列表页的骨架几乎一模一样——顶部的筛选条件、中间的表格和操作栏、底部的分页再加一个批量删除或者批量导出。我刚工作那会儿每接到一个新模块第一反应就是复制上一个页面的代码改改字段、换换接口半天能出一个能跑的页面。但几个月后噩梦就来了有的页面筛选后没有重置页码有的页面全选只选中了当前页有的页面排序状态一刷新就丢了还有的页面表格和分页的状态散落在各个组件里改一个功能要翻好几个文件。后来我下定决心把这套逻辑统一拿出来用 Vue3 的组合式函数和泛型组件重新做了一遍封装也就是这篇文章要聊的内容——列表与表格的分页、筛选、排序、批量操作和 Hook 封装全部基于 Vue3 的核心语法和组件模式。这篇内容适合正在用 Vue3 写后台管理系统、已经对 Composition API 有基本了解、想把手头重复的列表代码整理成可复用模块的开发者也适合那些面试前想系统梳理表格场景核心点的人。我会从需求拆解讲起把每一步设计背后的理由、踩过的坑、以及最终的代码形态都放出来你完全可以照着这套思路去重构自己的项目。1. 表格列表需求的共性拆解每个列表页都在重复什么先把一个标准后台列表页的痛点拆开看。表面上每个页面都不同但抽掉业务字段之后所有页面共享的状态结构和交互逻辑几乎是一样的。1.1 状态层面的共性几乎所有列表页都需要维护以下这组状态查询参数用户在筛选区域填的输入框、下拉框、日期范围等条件通常会组装成一个对象传给后端分页信息当前页码、每页条数、总条数表格数据当前页要展示的记录数组加载状态首次加载、筛选后加载、分页切换时的 loading 状态选中状态勾选了哪些行以及更复杂的跨页是否保留选中排序状态当前排序的字段和排序方向有些系统还支持多字段排序。在没有封装的情况下每个页面都会用 ref 把这些状态声明一遍然后在 methods 或者普通函数里写一模一样的数据获取逻辑。这不仅是代码重复的问题更大的隐患是行为不一致——A 页面筛选后记得回到第一页B 页面忘了产品验收的时候就会发现同样的操作在不同页面表现不同这比代码冗余更让人头疼。1.2 交互层面的共性除了状态交互流程也是一套固定套路页面加载时自动拉取第一页数据点击查询/搜索时带着最新条件回到第一页重新拉取点击重置时清空条件并回到第一页拉取切换页码或改变每页条数时带着现有条件拉取新数据点击表头排序时带着排序字段和方向重新拉取勾选行、全选、批量操作后刷新列表或删除选中项。其中第 2、3 条是最容易出问题的。很多新手会把查询参数和分页参数分开管理一旦筛选条件发生变化页码还停留在上一次的位置。比如你在第 5 页输入了一个关键词筛选结果接口返回的是新条件下的第 5 页——如果这个关键词匹配的总数据量只有两页你就会看到一个空列表而根本问题只是页码没有重置。正确的做法是查询条件的任何变化都要让分页器回到第一页。这条规则听着简单但在封装设计时需要考虑清楚触发时机因为我们既不能每次输入框一变就触发请求也不能在点击查询之前就偷偷改了页码导致用户困惑。通常的做法是维护两个对象一个用于绑定表单formModel一个用于真正发送请求的查询参数queryParams。点击查询时才把 formModel 深拷贝给 queryParams同时把 pageNo 重置为 1再执行拉取动作。这样就保证了输入过程中修改条件是不会骚扰接口的。提示不要直接在表单的 change 事件里去重置页码并请求除非你的筛选是即时搜索交互。后台管理的标准的查询-重置模式下用户期望自己点击查询按钮后才生效。1.3 为什么需要统一封装当我数了一下自己负责的模块有 30 多个列表页面时我意识到继续复制粘贴只会让维护成本指数上升。统一的封装可以带来三个直观的好处行为一致筛选、重置、分页、排序的触发逻辑由同一套代码管理用户不管在哪个页面操作体验都一样心智负担小新页面只需要配置请求函数、表格列、表单字段不需要关心内部状态流转修改成本低比如后端要求所有列表接口新增一个是否需要返回总数的参数或者统一的错误处理逻辑变更只需要改一处。这个先把共性抽出来的过程其实也是 Vue3 组合式函数最典型的应用场景。接下来我按分页、筛选排序、批量操作、Hook 封装、泛型组件这几个部分逐步拆开说。2. 分页逻辑的设计取舍前端分页与服务端分页的边界分页看着是最简单的功能实际上只要多问几个如果就能发现不少设计点。先说两种分页模式再说我的选择标准。2.1 前端分页的适用场景前端分页指的是后端一次性把所有数据返回前端在内存里做 slice 切页。这个方案只适合两种场景数据量上限明确且很小比如一个用户下的标签列表、配置项列表总量可能就几十条后端接口不支持分页参数且没有改造成本。前端分页的好处是切换页码无需重新请求接口体验上极快。但它的缺点也很致命数据量一大接口响应变慢、浏览器内存吃紧。我之前接手过一个旧系统列表接口每次返回全量数据最多的时候上万条记录全部渲染到 DOM 上页面卡到滚动都掉帧。后续改造第一步就是让后端支持 LIMIT/OFFSET然后把分页模式切换成服务端分页。所以我的建议是对于任何潜在数据量超过几百条的业务列表直接按服务端分页设计前期多写一点代码能避免后期大面积返工。2.2 服务端分页的核心状态流服务端分页模式下前端要维护的核心状态就是pageNo和pageSize以及后端返回的total。关键点在于调用接口的参数必须同时包含查询条件和分页参数缺一不可。这里有一个很容易写的反模式我反复在一些项目里见到// 反模式把分页参数存在组件内部 ref 里请求时单独读取 const pageNo ref(1) const pageSize ref(20) function loadData() { api.list({ ...filterForm.value, pageNo: pageNo.value, pageSize: pageSize.value }) }这种写法能跑但你会在多个函数里反复手动组合这两个来源的参数并且后续做 Hook 封装时要多传两个 ref 进去接口函数签名会非常啰嗦。更好的方式是把分页参数和查询条件放进同一个状态对象里统一管理。我们后面 Hook 封装时这个状态对象就是整个表格逻辑的单数据源。2.3 每页条数变化的处理细节除了页码切换还有一个容易被忽略的细节是 pageSize 变化。假设用户当前在第 10 页每页 20 条现在把每页条数改成 50如果仍然停留在第 10 页那么实际展示的数据区间就会跳变用户很难理解发生了什么。行业通用的交互方案有两种一种是修改 pageSize 后重置 pageNo 为 1另一种是用一个换算公式尽量保持用户看到的起始位置不变比如新页码 floor((旧页码 - 1) * 旧pageSize / 新pageSize) 1。第一种方案简单粗暴大多数后台管理系统都用这个第二种更精细但只有像 Grove 这类数据查看器才会刻意设计。我建议后台管理直接用方案一pageSize 变化时 pageNo 归 1。原因是业务列表很少需要精确保持滚动位置用户改变每页条数通常就是想换个更大的视图从第一页开始看是完全合理的行为。2.4 后端分页接口的约定问题前端封装做得再好如果后端接口的分页参数命名不统一照样要出问题。有的接口用page、limit有的用pageNum、pageSize有的用offset、rows。我在做 Hook 封装时会同时支持两种最常见风格并在封装的请求函数里做一层适配。还有一种更隐蔽的情况后端明明要的是 0 起始的下标前端给的是 1 起始的页码。比如点击第 1 页前端传pageNo: 1后端内部计算出offset (pageNo - 1) * pageSize这没问题但有些后端懒得算要求前端直接传offset: 0那就是(1-1)*200。这种约定差异如果不在请求函数里抹平换一个接口就能踩坑。我封装时会固定暴露pageNo和pageSize给业务页面用内部再去适配后端参数。提示设计接口时优先统一约定为pageNo从 1 开始和pageSize前端代码语义更清晰也符合多数 UI 组件库的页码概念。3. 筛选、排序与表格状态的联动一个值得单独说道的细节筛选和排序单独拎出来每个都简单但它们和分页、请求之间的联动关系才是最考验代码组织能力的地方。3.1 查询参数与表单状态的解耦前面提过维护一个绑定表单的formModel和一个真正发送请求的queryParams这是第一步。但接下来还有几个细节需要注意。一是重置操作的粒度。常见的重置有两种一种是把表单重置为空白初始值另一种是重置为首次进入页面时的默认值。不要小看这个区别。有些列表默认带一个状态条件比如只显示未处理用户改成全部后点击重置大多数产品预期是回到只显示未处理这个业务默认值而不是把下拉框清空。所以设计时不要写死formModel {}而要把初始默认值对象保存起来重置时使用它。二是避免表单校验打断请求。有些筛选表单使用了表单校验比如日期范围必填。正确做法是在点击查询时先执行校验校验通过后再组装 queryParams 并请求。但如果封装层面把请求逻辑写在 Hook 里表单校验写在组件里就需要通过返回值或者回调来保证执行顺序。我在封装时会让search函数返回一个Promise组件在调用前自行完成校验校验不通过就return不调用search这样职责边界很清晰。三是深拷贝的必要性。表单对象如果用reactive声明直接赋值给 queryParams会带着响应式引用关系。后续修改表单时就可能意外改动 queryParams导致还没点查询数据却已经被过滤了这种幽灵 bug。所以组装 queryParams 时务必JSON.parse(JSON.stringify(...))或使用工具函数深拷贝。这一步在面试里也常被问到属于看着不起眼但影响正确性的细节。3.2 表格排序的监听与参数传递Element Plus 的el-table提供了sort-change事件但很多人在监听处理后会把排序方向和字段名存成一个固定结构导致和不同后端的字段约定对不上。先看 Element Plus 的事件参数sort-change会回调{ column, prop, order }其中order只有三个值ascending、descending、null。null表示取消排序。而后端接口通常希望收到sortField: 字段名和sortOrder: asc | desc如果不做转换就直接传会出现传ascending这种前端独有的值。我在封装里的处理方式是把order映射成asc/desc/并在sort-change回调里赋值给 queryParams同时当成条件变化触发页码重置和请求。还有一个细节是默认排序——如果列表首次加载就需要按某个字段排序不要依赖el-table的default-sort属性因为它只影响表格展示不会主动触发事件。正确的做法是在 queryParams 的初始值里直接带上排序字段。3.3 查询条件中包含日期范围的处理后台列表特别常见的日期范围筛选前端控件通常是[startTime, endTime]这种数组但接口字段往往要拆成两个独立的字段传。这个转换放哪里做我的习惯是在组装 queryParams 时统一平铺。不要在表单绑定阶段就拆因为拆完数组之后回填就会出现麻烦下拉回显时还得组装回去。而是在buildParams这个纯函数里做转换这样前端表单结构和后端接口字段结构解耦后续接口字段改名时只需要改这一个函数。3.4 筛选与排序的共同重置策略总结筛选、排序、分页的联动策略我总结成一张简单的规则表方便你照着设计自己的封装触发动作是否重置页码是否触发请求说明点击查询是是把表单值同步到 queryParams点击重置是是用初始默认值覆盖表单页码切换否是只改 pageNopageSize 变化是是回到第一页排序变化是是排序字段加入 queryParams表单输入中否否不实时请求这张表就是后面 Hook 封装的行为基准。4. 批量操作与跨页选中最容易被忽视的坑批量操作包括批量删除、批量导出、批量审批核心难点其实不在操作本身而在全选的语义。4.1 el-table 全选的两种语义Element Plus 的表格选择列默认行为是当数据刷新后已勾选状态会保留在组件内部。但如果你点击了表头的全选复选框它只能选中当前页所有行数据切换到另一页后之前勾选的行虽然没有清空但你再点全选时它会基于当前页数据重新计算很容易出现第一页全选后翻到第二页再点全选结果只选中了第二页甚至取消了一些之前的选中这种奇怪体验。问题的本质在于用户心里的全选到底是选中当前页全部还是选中所有满足条件的数据。这就是产品逻辑的分叉点。4.2 只做当前页全选的简单方案如果业务场景明确不需要跨页选择比如批量操作在翻页后要保持选中行仍然存在但用户一般不指望全量操作那么你可以简单地维护一个selectedRows数组监听selection-change事件把它赋值给它就行。删除成功后清空数组。这个方案实现成本低但要确保翻页后已勾选行还在——因为 el-table 默认会对新渲染的行保留选中状态只要行的row-key属性配置正确翻页后刷新数据之前选中的行依然会保持勾选。这里有个关键点不配置row-key时刷新数据会导致选中状态丢失。给el-table加上row-keyid选中的行才能稳定保留。4.3 跨页全选与半选的处理如果你的业务确实需要跨页全选那就要引入更严谨的选中管理。我采用的方案是不直接依赖selection-change作为唯一数据源而是自己维护一个选中的 ID 集合。思路如下用ref维护selectedRowKeys这个Set行勾选变化时用toggleRowSelection/selection-change事件去同步selectedRowKeys表头全选勾选时把当前页所有行的 id 加入集合如果全选被取消把当前页所有行 id 从集合中移除翻页加载新数据后用row-key和selectedRowKeys反推哪些行应处于勾选状态通过toggleRowSelection(row, true)重新设置。核心难点在第 3、4 步。直接监听selection-change再赋值会覆盖其它页的选中状态正确做法是让selection-change只负责把界面的勾选结果同步到集合而全选按钮的全选当前页/取消当前页逻辑单独写处理函数。考虑到实现复杂度实际开发里我建议保守一点除非产品明确要求否则默认只做当前页全选 翻页保留已选的模型。绝大多数后台业务中用户的批量操作对象只是当前看到的这一批数据跨页全选有点像全选后我又筛了个条件再全选状态管理复杂度会指数上升操作结果也未必符合用户预期。4.4 批量删除完成后的联动刷新批量删除成功之后有一个细节很容易忽略删除后当前页可能只剩空数据或者删掉的是最后一页的最后几条此时应该把页码往前调整。否则用户会看到一个空白页误以为操作失败了。我在封装里提供了一个reload函数它内部会判断如果当前页数据删除后为空且 pageNo 大于 1就先执行pageNo--再触发请求。这个逻辑同样适用于单条删除。还有一个细节是批量操作进行中要锁住按钮防止重复提交。我给按钮绑定的loading状态和表格加载状态是分开的因为批量操作的 loading 只作用于那个按钮不应该让整个表格重载否则用户会看到表格内容闪烁。提示批量操作的二次确认弹窗里最好展示已选 X 项的数量并说明是全选了当前页还是全部页。这个数量直接用selectedRows.length即可如果跨页选中的话用集合 size。5. 用 Hook 抽取表格逻辑useTable 组合式函数落地前面聊了一大堆设计原则现在到了代码落地的环节。我会以一个综合了分页、筛选、排序、批量选择和请求调用的useTable为例展示 Vue3 组合式函数怎么把这套逻辑真正收敛起来。5.1 Hook 的输入与输出设计在动手写之前先明确这个 Hook 要接收什么、返回什么。输入fetchApi一个接收查询参数、返回Promise{ list, total }的函数initParams初始查询参数包括筛选默认值、排序默认值、分页默认值options可选配置比如是否立即加载、请求失败是否提示、rowKey 字段名等。输出数据与加载状态tableData、loading、total分页状态与操作pageNo、pageSize、pageChange、sizeChange排序处理handleSortChange筛选操作search、reset选择相关selectedRows、selectedRowKeys、clearSelection底层函数getList、reload。这样设计的好处是业务组件不需要关心请求是怎么发出去的也不需要自己声明一堆 ref 再用 watcher 串联。所有联动逻辑在 Hook 内部完成组件里只需要调函数。5.2 useTable 核心代码实现先看一个简化但完整的实现后续再讲关键点import { ref, reactive, onMounted } from vue export function useTable(fetchApi, initParams {}, options {}) { const { immediate true, rowKey id } options // 用 reactive 统一管理查询参数避免手动拼接 const queryParams reactive({ pageNo: 1, pageSize: 10, ...initParams }) // 保存初始默认值供重置时使用 const defaultParams JSON.parse(JSON.stringify(queryParams)) const tableData ref([]) const total ref(0) const loading ref(false) // 选中状态 const selectedRows ref([]) const selectedRowKeys new Set() // 请求核心函数 async function getList() { loading.value true try { const params JSON.parse(JSON.stringify(queryParams)) const res await fetchApi(params) tableData.value res.list ?? [] total.value res.total ?? 0 } finally { loading.value false } } // 页码切换 function pageChange(page) { queryParams.pageNo page getList() } // 每页条数变化 function sizeChange(size) { queryParams.pageSize size queryParams.pageNo 1 getList() } // 点击查询用外部传入的最新筛选值覆盖 queryParams function search(values) { Object.keys(values || {}).forEach((key) { queryParams[key] values[key] }) queryParams.pageNo 1 getList() } // 重置回到初始默认值 function reset() { Object.keys(defaultParams).forEach((key) { if (key ! pageNo key ! pageSize) { queryParams[key] defaultParams[key] } }) queryParams.pageNo 1 getList() } // 排序处理 function handleSortChange({ prop, order }) { if (!prop) { delete queryParams.sortField delete queryParams.sortOrder } else { queryParams.sortField prop queryParams.sortOrder order ascending ? asc : order descending ? desc : } queryParams.pageNo 1 getList() } // 同步选中集合 function syncSelection(rows) { selectedRows.value rows selectedRowKeys.clear() rows.forEach((row) selectedRowKeys.add(row[rowKey])) } // 当前页全选/取消 function handleSelectAll(rows, isSelect) { rows.forEach((row) { if (isSelect) { selectedRowKeys.add(row[rowKey]) } else { selectedRowKeys.delete(row[rowKey]) } }) // 这里需要反向同步 el-table 的选中状态 } // 清空选中 function clearSelection() { selectedRows.value [] selectedRowKeys.clear() } function reload() { if (tableData.value.length 0 queryParams.pageNo 1) { queryParams.pageNo - 1 } getList() } if (immediate) { onMounted(getList) } return { queryParams, tableData, total, loading, selectedRows, selectedRowKeys, pageChange, sizeChange, search, reset, handleSortChange, syncSelection, handleSelectAll, clearSelection, getList, reload } }这段代码里其实还有几个值得展开讲的地方。5.3 为什么用 reactive 而不是多个 ref在 Hook 内部我选择把 pageNo、pageSize、sortField、sortOrder、筛选字段全部放在一个reactive对象里。这样搜索引擎参数时只需要一次性深拷贝这个对象不会漏字段也不会出现页面里改了 A 条件请求里只有一个旧值这种错位。有些开发者习惯把 pageNo 和 pageSize 单独抽成 ref理由是分页器需要显式绑定。实际上 Element Plus 的分页器可以直接绑定queryParams.pageNo响应式嵌套对象在 Vue3 里是完整支持的所以没有维护成本问题。一个状态对象打天下比多个 ref 再加 computed 组装心智负担更小。5.4 search 和 reset 的参数传递方式刚才代码里search(values)接收一个外部传入的对象把它的字段覆盖到 queryParams 上。这要求组件的表单对象和 queryParams 里的字段名一致。有人会问为什么不直接在 Hook 里用 reactive 创建 formModel我试过在 Hook 里创建 formModel但发现表单的校验规则、字段类型和展示逻辑往往和页面强绑定强行塞进 Hook 会让 Hook 变得很重。所以我的取舍是Hook 只管请求参数表单由组件自己管只在点击查询时把表单值传给search。reset则相反——因为 Hook 内部保存了defaultParams所以重置时组件只需要调用reset()并把自己的 formModel 恢复成默认值。两者配合时要注意重置后组件里的表单回显值也必须更新最好在声明 formModel 时就把默认值定义成一个独立常量组件和 Hook 都引用它。5.5 封装后的组件侧使用示例下面是一个业务组件使用useTable的完整骨架script setup import { reactive } from vue import { useTable } from /hooks/useTable import { fetchUserList, deleteUsers } from /api/user // 表单默认值组件侧维护 const defaultForm { keyword: , status: , dateRange: [] } const formModel reactive({ ...defaultForm }) const { queryParams, tableData, total, loading, selectedRows, pageChange, sizeChange, search, reset, handleSortChange, syncSelection, clearSelection, getList } useTable(fetchUserList, { ...defaultForm, sortField: createTime, sortOrder: desc }, { rowKey: id }) function handleSearch() { search({ ...formModel }) } function handleReset() { Object.assign(formModel, defaultForm) reset() } function handleBatchDelete() { // 调删除接口后 reload } /script页面里表格部分的模板代码就非常薄了el-table v-loadingloading :datatableData row-keyid selection-changesyncSelection sort-changehandleSortChange el-table-column typeselection width50 / !-- 业务列省略 -- /el-table el-pagination background layouttotal, sizes, prev, pager, next, jumper :totaltotal :page-sizequeryParams.pageSize :current-pagequeryParams.pageNo :page-sizes[10, 20, 50, 100] current-changepageChange size-changesizeChange /到这里一个页面里原来最啰嗦的 100 多行逻辑就收敛成了几十行业务配置而且每个页面的行为都一致了。6. 表格组件的泛型封装类型安全与可扩展性Hook 解决了逻辑复用但视图层还有个问题每个页面还是要写一遍几乎一样的el-table结构包括 loading、selection 列、空数据状态等。更进一步我们希望表格组件能对业务行数据类型做类型约束在写列配置时就享受到 IDE 的类型提示。这就轮到泛型组件登场了。6.1 泛型组件的基本形态Vue3 的script setup里定义泛型组件需要用defineProps配合generics选项。以 TypeScript 为例script setup langts genericsT extends { [key: string]: any } import type { TableColumn } from /types/table interface Props { columns: TableColumnT[] data: T[] loading?: boolean rowKey?: keyof T | string selectable?: boolean } definePropsProps() // 泛型事件向父组件抛出当前行类型 const emit defineEmits{ (e: row-click, row: T): void (e: selection-change, rows: T[]): void (e: sort-change, sortState: { prop: keyof T; order: asc | desc | }): void }() /script这样写之后在父组件使用UserTable :columnscolumns :datatableData :loadingloading row-keyid selection-changesyncSelection sort-changehandleSortChange /其中columns的类型由TableColumnT决定T 在父组件里是UserInfo接口所以列配置里写prop: userName时 IDE 会给出正确的字段提示字段名打错了会直接报红。这在项目大、字段多的时候特别有价值。6.2 列配置驱动的动态列渲染把列做成配置数组之后列本身还可以扩展很多能力比如是否需要排序、宽度、是否展示、是否支持操作列插槽。我常用的一种列类型定义是export interface TableColumnT { prop: keyof T string label: string width?: number | string minWidth?: number | string sortable?: boolean | custom formatter?: (row: T, value: any) string slots?: { default?: (row: T) VNode header?: () VNode } }formatter可以处理纯展示的格式化不需要额外写插槽需要复杂交互的列才用slots。这样大部分列表页的列都是纯配置项只有少数列需要自定义渲染组件内部的模板复杂度也控制在合理范围。6.3 表格组件与 Hook 的组合关系泛型表格组件负责渲染和事件抛出useTable负责状态和请求逻辑两者在页面组件里组合。最终形成的文件组织方式是这样的hooks/useTable.ts状态管理通用逻辑components/BaseTable.vue通用表格容器api/xxx.ts每个模块的接口函数views/xxx/index.vue页面组件只写表单配置、列配置、少量交互函数。有一次新来的同事接一个列表模块当天就完成了。我帮他看代码的时候想找他踩坑的地方翻了半天没找到——因为所有容易出问题的行为都在 Hook 里固定好了。那一刻我确实觉得这套封装值了。6.4 封装时要避免的过度设计说到最后我也得泼一盆冷水。表格封装很容易做过火。我见过有人把列配置、权限、字典翻译、导出、列宽拖拽、显隐列全部塞进一个超级表格组件结果组件光 props 就有二十多个维护成本反而比每个页面单独写还高。我的原则是两个凡是凡是超过 80% 页面都需要的才放进基础封装凡是只在少数页面出现的一律不放进基础封装需要时在页面里自己扩展。列宽拖拽、列显隐这种功能一两个页面需要就用表格的局部特效做所有页面都需要的基础场景才值得放进去。封装不是目标用最小的维护成本支撑最多的业务场景才是目标。7. 我踩过的几个坑和最终沉淀的经验最后聊一些代码之外的东西。这些是我在实际项目中踩过、也修复过的具体坑如果你正在做类似的封装大概率能提前避开。第一个坑是selection-change触发的时序问题。绑定selection-change之后在syncSelection里更新selectedRows但如果同时又在 Hook 内部调用了clearSelection()可能会因为清空行为触发一次selection-change回调导致上一次选中的数据被意外清掉。解决方案是用nextTick包裹清空操作或者调整清空逻辑的先后顺序先置空数据源再让表格解除选中。第二个坑是接口返回数据结构不一致。有的接口返回{ records: [], total: 100 }有的返回{ rows: [], count: 100 }更有一些老接口直接返回{ data: { list: [...] }, total: 0 }。如果 Hook 内部写死了res.list和res.total换个接口就崩。最终我在fetchApi的封装处做了一个统一的接口适配层不管后端怎么命名最终返回给useTable的都是{ list, total }结构。第三个坑是筛选区日期组件在重置时回显异常。defaultForm里日期范围是空数组组件里绑定了日期范围选择器重置时 Object.assign 把空数组赋值过去但 Element Plus 的日期选择器在值变更为空数组时如果绑定的类型是 null 不是 []会出现显示异常。这类组件库的边界问题只能在封装测试阶段多覆盖几种重置场景。第四个坑是排序与分页混在一起的接口参数污染。有一个页面在排序完成后翻页发现数据又变回未排序状态。查到最后是接口的排序参数只能跟分页参数同时传递但后端的实现里有 bug页码变化时没读排序参数。前端排查时一度以为是自己状态丢值最后只能让后端修复。这也提醒我排序状态必须和分页参数放在同一个 queryParams 对象里传递因为这个同传能减少双方约定不一致的概率。第五个坑是切换页面时旧页面的请求覆盖新页面。用户先在一个列表页发起了请求快速切换到另一个列表页如果第一个请求尚未返回它的响应可能会渲染到新页面组件上。解决方式是在组件销毁时取消未完成的请求或者在 fetch 函数里为请求加上类似 AbortController 的取消机制。这个点在我最初封装时完全没考虑直到线上出现列表数据闪成上一个页面数据的脏数据现象才警觉。除了具体的坑我再分享几条沉淀下来的使用建议。第一不要为所有页面强行套同一个分页器。有的页面是列表 详情跳转逻辑有的页面是树表 懒加载我会在 BaseTable 里允许pagination属性传入 false这些特殊页面就不显示分页器逻辑上照常走 useTable 的 getList。第二筛选表单的字段命名要和后端字段保持一致避免在前端组件层做大量字段名翻译。比如后端叫createdAt前端表单就老老实实叫createdAt不要叫createTime否则每次请求都要写映射函数纯属给自己加负担。第三排序的默认可视化状态需要通过 el-table 的default-sort声明。因为初次进入页面时queryParams 里已经带了默认排序但表格表头的排序图标不会自动点亮。我得在页面里给 el-table 加 default-sort 属性让视觉状态和后端实际排序逻辑一致。第四测试用例可以围绕分页边界写。我在封装后写了几个比较关键的测试场景第一页筛选、最后一页删到空、pageSize 从大改小、跨页选中后再翻页、排序切换后页码重置。这些场景覆盖了绝大部分开发中会遇到的回归问题每次改封装代码都要跑一遍。如果你现在正准备把项目里的列表页做一轮重构我的建议是别一上来就写代码先在纸上把上文的行为规则表列清楚和产品确认清楚全选语义再动手封装。实现本身并不复杂真正容易出问题的都是这类看不见的交互边界。一套好的封装用起来之后你会明显感觉到新页面开发的速度和稳定性都上了一个台阶后续再遇到类似场景时专注点也从怎么让它能跑变成了业务逻辑怎么表达得更好。