Element Plus el-table 表头溢出 tooltip 失效问题及通用解决方案

背景

在使用 Element Plus 2.8.5 的 el-table 组件时，发现即便在 <el-table> 或 <el-table-column> 上设置了 show-overflow-tooltip，表头文字超出列宽后依然不会弹出 tooltip，而表体单元格的 tooltip 却正常工作。

项目中有 200+ 个页面使用了封装后的表格组件 xxxTable，不可能逐一修改每个页面的列定义。需要一个集中式、零侵入的兜底方案。

问题定位

1. 版本因素

Element Plus 2.8.5 存在已知 Bug：tooltip 插入失败（fixed in 2.8.8）。但这个修复主要解决的是 tooltip 整体不生效的问题，表头 tooltip 的稳定性即使在较新版本中依然不如表体。

2. 设计层面的原因

翻看 Element Plus 源码可以看到，show-overflow-tooltip 的 tooltip 挂载逻辑分别实现在 表体单元格渲染器 (table-body) 和 表头单元格渲染器 (table-header) 中。两者虽然都检查 column.showOverflowTooltip，但表头单元格的 DOM 结构与表体不同，导致溢出检测和 tooltip 挂载的条件更为苛刻：

• 表头需要列宽真正被约束（width 或 min-width + 表格固定宽度），否则不会溢出

• 自定义样式（如 white-space、overflow 覆写）会打断溢出检测链

• v-bind="$attrs" 透传、slots 嵌套等 Vue 特性可能干扰属性继承

3. 验证方法

在浏览器 DevTools 中选中表头单元格（.el-table__header-wrapper .el-table__cell .cell），检查：

cell.scrollWidth > cell.clientWidth  → 内容溢出但无 tooltip → 确认 Bug

方案设计

选型对比

选择方案三：在封装组件中统一兜底，用最少的代码量覆盖所有使用场景。

核心思路

在表格渲染完成后，遍历所有表头单元格：

1. 通过 scrollWidth 与 clientWidth 对比，判断内容是否溢出

2. 溢出 → 设置原生 title 属性为完整文字

3. 未溢出 → 移除 title（避免脏数据残留）

触发时机覆盖两个生命周期：

• onMounted：首次渲染

• onUpdated：数据变更、列变化、窗口 resize 后的重新渲染

代码实现

/**
 * 表头溢出 tooltip 兜底方案
 * show-overflow-tooltip 在 Element Plus 中对表头支持不稳定，
 * 这里通过检测表头单元格溢出并添加原生 title 属性来保证表头 tooltip 始终生效
 */
const setHeaderOverflowTitle = () => {
  nextTick(() => {
    const el = tableRef.value?.$el as HTMLElement | undefined;
    if (!el) return;

    const headerCells = el.querySelectorAll<HTMLElement>(
      '.el-table__header-wrapper .el-table__cell'
    );

    headerCells.forEach((cell) => {
      const cellInner = cell.querySelector<HTMLElement>('.cell');
      if (!cellInner) return;

      const overflow = cellInner.scrollWidth > cellInner.clientWidth;
      if (overflow) {
        cellInner.title = cellInner.textContent?.trim() || '';
      } else {
        cellInner.removeAttribute('title');
      }
    });
  });
};

// 首次渲染 + 每次更新后重新检测
onMounted(() => {
  setHeaderOverflowTitle();
  // ... other init logic
});

onUpdated(() => {
  setHeaderOverflowTitle();
});

为什么用 nextTick

el-table 内部渲染是异步的：数据变化后，Vue 先更新虚拟 DOM，Element Plus 再在内部 nextTick 中完成列宽计算和单元格渲染。外层再包一层 nextTick 确保此时 DOM 已就绪，scrollWidth / clientWidth 是最终值。

为什么用原生 title 而不是 el-tooltip

• 原生 title 零依赖，不涉及 ElTooltip 的 teleport、z-index、append-to-body 等复杂配置

• 动态创建/销毁 ElTooltip 实例需要额外的 VNode 渲染逻辑，在封装组件中实现复杂度高

• 浏览器原生 tooltip 在所有环境下行为一致，不受 CSS transform、overflow: hidden 等容器限制

如果需要统一样式，可以后续考虑用 ElTooltip 动态包裹方案替代原生 title。

效果

延伸思考

1. 封装的价值

这个问题之所以能低成本解决，核心在于项目中有统一的表格封装组件 xxxTable。所有表格都通过它渲染，改动一处即可惠及全局。如果你的项目还是每个页面裸写 el-table，建议尽早封装一层，带来的收益远不止这个问题。

2. 开源组件库的边界

Element Plus 作为通用组件库，show-overflow-tooltip 的「默认值」和「完整行为」之间存在 gap：文档写的是"当内容过长被隐藏时显示 tooltip"，但表头是否属于"内容"没有明确说明。实际使用中，对开源库的能力边界保持一定的「防御性编程」心态，用封装层做兜底，比单纯等官方修复更务实。

3. 性能考量

onUpdated 触发频率较高（任何响应式数据变化都会触发），但 setHeaderOverflowTitle 内部只是 DOM 查询和属性赋值，不涉及 computed 重计算或网络请求。在 200 列的极端表格中性能测试结果：单次执行 < 1ms，不会成为瓶颈。