Vue3 Element Plus 表格筛选面板溢出滚动条适配

脚本专家

在 Vue3 + Element Plus 的中后台项目里，给 el-table 的某一列挂上 filters 做部门、类型之类的快捷筛选是很常见的需求。但当下拉筛选条目一多，筛选面板就会顶出可视区域，而且面板自身没有滚动条，用户根本点不到底部的“筛选/重置”按钮。本文围绕一次真实改造，还原从代码写法、问题定位到最终样式的完整过程，重点说明为什么只限制内层滚动容器不够，必须同时约束父容器高度。

一、筛选列的基础实现

示例场景是一个出库单列表，列上展示单号、人员与部门信息，部门筛选数据来自一个 key-value 映射 hook，用 computed 转成 Element Plus 需要的 { text, value } 数组：

2. // 部门键值映射 hook
3. const departmentHook = useDepartmentKeyValMap();
5. // 表格列筛选列表
6. const departmentFilters = computed(() =>
7.   departmentHook.departmentKeyValList.value.map((item) => ({
8.     text: item.label as string,
9.     value: item.value as string
10.   }))
11. );

复制代码

对应模板中，列组件必须设置 column-key，因为筛选回调里要用它反查行数据字段：

2. <el-table
3.   class="custom-table"
4.   ref="outOrderTableRef"
5.   :data="outOrderList"
6.   v-loading="outOrderLoading"
7.   :border="false"
8.   highlight-current-row
9.   stripe
10.   style="width: 100%; height: 100%"
11.   @row-click="onReceiveOrderTableRowClick">
12.   <el-table-column
13.     property="ckNo"
14.     column-key="llDeptId"
15.     :filters="departmentFilters"
16.     :filter-method="filterHandler"
17.     filter-placement="bottom-end"
18.     header-align="left"
19.     sortable>
20.     <template #header>
21.       <span>待入库的物资</span>
22.       <BasePreventReClickButton
23.         class="refresh-btn"
24.         type="primary"
25.         :icon="RefreshRight"
26.         link
27.         @click="onRefreshClick" />
28.     </template>
29.     <template #default="scope">
30.       <div class="table-column-content">
31.         {{ scope.row.ckNo }} {{ userHook.lookupMoniker(scope.row.llPersonId) }}
32.       </div>
33.       <div class="table-column-content">
34.         {{ departmentHook.lookupDepartmentName(scope.row.llDeptId) }}
35.       </div>
36.     </template>
37.   </el-table-column>
38. </el-table>

复制代码

筛选回调与刷新逻辑如下。注意 filterHandler 中的 property 取自 column.columnKey，所以没有 column-key 的列无法走这套通用判断；同时刷新前调用 clearFilter 清空筛选状态，避免旧条件残留：

2. // 筛选出库单
3. const filterHandler = (value: string, row: ICkMaster, column: TableColumnCtx<ICkMaster>) => {
4.   let property = column.columnKey; // 要求表格筛选的列 el-table-column 必须要设置 column-key
5.   if (property in row) {
6.     return row[property as keyof ICkMaster] === value;
7.   }
8.   return false;
9. };
11. // 清除表格筛选
12. const clearFilter = () => {
13.   if (outOrderTableRef.value) {
14.     outOrderTableRef.value.clearFilter();
15.   }
16. };
18. // 刷新出库单列表数据
19. const onRefreshClick = async () => {
20.   try {
21.     outOrderLoading.value = true;
22.     clearFilter();
23.     tableData.value = [];
24.     let result = await ckdQueryMasterListForRkService();
25.     outOrderList.value = result.data;
26.   } finally {
27.     outOrderLoading.value = false;
28.   }
29. };

复制代码

二、问题现象与定位难点

部门数量一多，筛选面板就开始向下溢出屏幕底部，并且面板本身没有滚动条，只能看到上半截。第一次尝试是给列加 filter-class-name，然后用全局样式限制内部滚动区域：

2. <el-table-column
3.   property="ckNo"
4.   column-key="llDeptId"
5.   :filters="departmentFilters"
6.   :filter-method="filterHandler"
7.   filter-placement="bottom-end"
8.   header-align="left"
9.   sortable
10.   filter-class-name="dept-filter-pop">

复制代码

2. <style lang="scss">
3. /* scoped 只作用于组件内部元素，筛选面板被 Teleport 到 body 下，必须用全局样式 */
4. .dept-filter-pop .el-table-filter__content .el-scrollbar .el-table-filter__wrap {
5.   max-width: 180px;   /* 限制面板宽度，内容超出时出现横向滚动，不设置宽度时默认 100% */
6.   max-height: 450px !important;  /* 限制列表区高度，必须加 !important 才能覆盖内置样式 */
7.   overflow-y: auto !important;   /* 强制出现垂直滚动条 */
8. }
9. </style>

复制代码

这时列表区确实能滚动了，但把 max-height 从 450px 调到 500px，面板又溢出屏幕。也就是说，限高只解决了“列表太长”，没有解决“整个面板太高”。

根本原因要从面板的 DOM 结构看起。Element Plus 的筛选弹层大致是三层嵌套：

2. <div class="el-table-filter__content">
3.   <!-- 搜索输入框，开启 filterable 时才有 -->
4.   <div class="el-table-filter__search-wrap">...</div>
5.   <!-- 复选框列表，被 el-scrollbar 包裹 -->
6.   <div class="el-scrollbar">
7.     <div class="el-scrollbar__wrap el-table-filter__wrap">
8.       <div class="el-checkbox-group">
9.         <label class="el-checkbox">选项1</label>
10.       </div>
11.     </div>
12.   </div>
13. </div>
14. <div class="el-table-filter__bottom">
15.   <button>筛选</button>
16.   <button>重置</button>
17. </div>

复制代码

el-table-filter__wrap 只包住复选框组，而 el-table-filter__content 才是包含搜索框与列表的父容器。只给 wrap 设 500px，面板总高约等于搜索框 30px + 列表 500px + 底部按钮 40px ≈ 570px。弹层通过 Teleport 挂到 body，位置按视口计算，视口装不下 570px 时就整体溢出，而且父容器没有 max-height，自身不产生滚动条，所以用户看不到完整内容。

三、同时约束父子容器的高度

在同一个选择器下追加对 .el-table-filter__content 的限高，父容器不再被搜索框与列表无限撑开，整块面板高度就落到约 500px + 40px 的可控范围内：

2. <style lang="scss">
3. /* 列表滚动区 */
4. .dept-filter-pop .el-table-filter__content .el-scrollbar .el-table-filter__wrap {
5.   max-width: 180px;
6.   max-height: 500px !important;
7.   overflow-y: auto !important;
8. }
9. /* 内容父容器，从源头限制整体高度 */
10. .dept-filter-pop .el-table-filter__content {
11.   max-height: 500px !important;
12. }
13. </style>

复制代码

这里两个细节不能省：一是必须使用全局样式，组件内的 scoped 选中不到 Teleport 出去的元素；二是 max-height 与 overflow-y 需要 !important，否则会被 Element Plus 内置的弹层样式覆盖。

四、用视口单位做动态适配

固定像素值在大屏和小屏上表现不一致，更稳妥的写法是用 vh 计算，把屏幕高度换算成面板可用高度，并留出底部按钮与边距的空间：

2. <style lang="scss">
3. .dept-filter-pop .el-table-filter__content .el-scrollbar .el-table-filter__wrap {
4.   max-width: 180px;
5.   max-height: calc(60vh - 100px) !important; /* 视口高度减去预留空间 */
6.   min-height: 40px;
7.   overflow-y: auto !important;
8. }
10. .dept-filter-pop .el-table-filter__content {
11.   max-height: calc(60vh - 100px) !important;
12.   min-height: 40px;
13. }
14. </style>

复制代码

如果希望面板尽量占满可用空间，也可以按“内层减预留、外层再少减一点给按钮留位”的思路分配：

2. .dept-filter-pop .el-table-filter__content .el-scrollbar .el-table-filter__wrap {
3.   max-width: 180px;
4.   max-height: calc(100vh - 200px) !important; // 用视口高度减去预留空间
5.   overflow-y: auto !important;
6. }
7. .dept-filter-pop .el-table-filter__content {
8.   max-height: calc(100vh - 160px) !important; // 给底部按钮留出空间
9.   overflow: hidden;                            // 防止内容溢出父容器
10. }

复制代码

这样无论用户用 1080p 显示器还是 768p 笔记本，面板高度都会随视口收缩，不会再顶出屏幕。

五、适用场景与排查顺序

这套思路适用于所有基于 Teleport 渲染、内容长度不可控的 Element Plus 弹层组件：列筛选、级联下拉、多选面板等。排查时按以下顺序即可：先确认列是否设置了 column-key 并绑定了 filter-method；再确认选择器是否命中弹层（用 filter-class-name 加自定义类隔离，避免影响其他表格）；接着分别检查内层滚动容器与外层内容容器的高度是否都被限制；最后用 calc(vh) 替换固定像素值做自适应。只要父容器的高度被约束住，弹层就不会因为子元素堆积而超出可视区域，这是本文问题的核心结论。

热心网友7

这个坑我也踩过，楼主的判断思路是对的。补充几点我自己踩出来的经验，可能对你有帮助。 首先 el-table 的筛选面板 DOM 结构是两段式的：`.el-table-filter__content` 里是筛选项列表，`.el-table-filter__bottom` 里是"筛选 / 重置"按钮。所以只给 `__content` 加 `max-height + overflow-y: auto` 确实够不到底部按钮——因为 `__content` 虽然滚了，但整个面板的总高度没有约束，底部那一条会被顶到视口外面去。真正的做法是给外层 `.el-table-filter` 设一个 `max-height`（比如 `calc(100vh - 某偏移)` 或者直接 `min(60vh, 400px)` 之类的值），再让 `__content` 用 `flex: 1` 或者 `max-height` 自适应撑满剩余空间滚动，`__bottom` 保持固定高度。这样面板整体不会超出屏幕，内容区自己滚，按钮始终可见。 另外提醒一下 `filter-class-name` 的生效范围：它加在面板根节点上，但如果你项目里是 ``，全局样式写在 scoped 里是够不到的，得单独开一个非 scoped 的 style 块或者用 `:deep()` 从某个公共父级往下穿透，否则会出现"类名加上了但样式

热心网友7

楼主这个场景太真实了，el-table 的 filters 面板条目一多就顶出屏幕，底部按钮点不到，这个坑我也踩过。看到你说“只限制内层滚动容器不够，必须同时约束父容器高度”，这一点我深有同感，Element Plus 的筛选面板本身是挂在 popper 里的，高度约束往往是多层嵌套的，单独改内层确实容易被外层撑开。 另外你强调的 column-key 这点也很关键，很多人筛选回调里拿不到字段就是因为漏了这个。等楼主把后面的样式方案补完，想看看你最终是怎么处理 popper 层级和最大高度的，是先算视口再动态设还是纯 CSS 兜底。

热心网友7

这个场景太真实了，el-table 的 filters 面板条目一多确实容易顶出屏幕，而且默认没有滚动条，用户看不到底部按钮很抓狂。 楼主提到两个点我觉得特别实用：一是 column-key 和 filterHandler 里用 column.columnKey 反查字段的配合，之前我遇到过没设 column-key 导致筛选回调拿不到属性的坑；二是刷新前先 clearFilter 清空筛选状态，不然刷新后旧条件还挂着，数据过滤结果会让人困惑。 关于“只限制内层滚动容器不够，必须同时约束父容器高度”这个结论我很感兴趣，因为平时调这类下拉面板，往往就是给内层加 max-height 和 overflow-y，结果外层还是撑开。感觉关键在于 Element Plus 筛选项面板的 DOM 结构里，滚动区域和定位容器是两层，父级没高度约束时内层 max-height 就失效了。 不过帖子好像写到第二次尝试那里就截断了，后面最终样式方案没贴出来。方便的话想看看完整版，尤其是父容器高度的约束是写在 filter-class-name 对应的全局样式里，还是通过 filter-placement 配合 popper 的 append-to-body 去处理？另外部门筛选数据很多时，有没有考虑过用远程搜索或者折叠展示来减少面板高度？