ECharts 饼图鼠标悬浮后标签 title 消失的问题

解决 ECharts 饼图鼠标悬浮后标签 title 消失的问题

TL;DR

饼图扇区外侧的文字标签,鼠标悬浮(hover)时,标签里的 title 那一行(甚至整块标签 + 引导线)会突然消失,移开鼠标又恢复。

这不是样式 bug,而是 ECharts 的标签防重叠布局 与 emphasis(强调)状态交互导致的。修复只有一句话:

在 emphasis 里显式声明 label.show: true 和 labelLine.show: true。

一、问题现象

一张常见的占比饼图,每个扇区外侧带文字标签,标签通常是两行结构:第一行是数值/百分比,第二行是标题(title)。

scss 复制代码

        ┌──────────────┐
        │  85% (17)    │  ← 数值行
   ╲    │  自动模式    │  ← 标题行(title)
    ╲   └──────────────┘
     ╱─────
    ╱  扇区

Bug 表现:

鼠标悬浮到某个扇区上时,该扇区标签里的 title 那一行(连同引导线)突然消失,只剩数值行,或整块标签都不见了;移开鼠标恢复。

排查时第一反应往往是「hover 触发了什么动画把标签顶出去」------其实不是,动效根本没动标签的位置。真正的根因在状态机里。

二、根因:emphasis 态「沿用隐藏状态」

ECharts 5 的饼图,当扇区标签显示在外侧时,引擎会自动做标签防重叠布局(labelLayout) :空间不够或标签互相遮挡时,它会隐藏部分标签、引导线,或其中某几行。

关键点来了:

一旦某段内容(比如 title 那一行)在普通态被防重叠布局标记为「隐藏」,当鼠标悬浮、扇区进入 emphasis 态时,ECharts 默认会「沿用这个隐藏状态」,而不会因为扇区被高亮就把它重新显示出来。

于是表现为:悬浮一下,title 就没了。不是 emphasis 把 title 藏起来的,而是 title 早就被防重叠布局判了「隐藏」,emphasis 只是没有把它捞回来。

这也解释了为什么「移开鼠标又恢复」------离开 emphasis 态后,回到了普通态的布局结果。

三、解法:emphasis 显式 `show: true`

既然问题是「emphasis 沿用隐藏状态」,那就在 emphasis 里显式声明依旧显示:

js 复制代码

series: [
  {
    type: 'pie',
    radius: ['40%', '65%'],
    label: { show: true, /* formatter / rich 等 */ },
    labelLine: { show: true },
    emphasis: {
      // 关键:显式声明强调态仍展示标签和引导线,
      // 既保留扇区默认的放大动画,又避免标签被 emphasis 态隐藏。
      label: { show: true },
      labelLine: { show: true }
    }
  }
]

加上这两行后:

扇区 hover 时默认的放大动画照常(没有禁用 emphasis);
标签和引导线不再因为「沿用隐藏状态」而消失,title 行稳定可见。

为什么不能指望默认值?

因为 emphasis 态不会自动继承普通态的全部显示设置 。普通态写了 label.show: true,不代表 emphasis 态也是 true------一旦普通态里这个标签被防重叠布局动态隐藏过,emphasis 态就会以「隐藏」为准。涉及 label / labelLine 可见性时,显式写 emphasis.label.show: true 比依赖默认值稳妥得多。

这也是这个 Bug 最容易踩坑的地方:配置看起来「我明明设置了 label.show: true 啊」,却忽略了它只对普通态生效。

四、最小复现代码

html 复制代码

<!DOCTYPE html>
<html>
<head><meta charset="utf-8" /></head>
<body>
  <div id="chart" style="width: 600px; height: 400px;"></div>
  <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
  <script>
    const chart = echarts.init(document.getElementById('chart'));
    chart.setOption({
      series: [{
        type: 'pie',
        radius: ['40%', '65%'],
        center: ['50%', '55%'],
        data: [
          { value: 17, name: '自动模式' },
          { value: 3,  name: '手动模式' }
        ],
        label: {
          show: true,
          formatter: (p) => `{a|${p.value} (${p.percent}%)}\n{a|${p.name}}`,
          rich: { a: { fontSize: 12, lineHeight: 20 } }
        },
        labelLine: { show: true },
        emphasis: {                         // ✅ 关键修复:强调态强制显示
          label: { show: true },
          labelLine: { show: true }
        }
      }]
    });
  </script>
</body>
</html>

想复现 Bug:把 emphasis 那段去掉,然后用更长的标签文案 + 更小的容器,制造出标签互相遮挡的场景,悬浮时就能看到 title 行消失。

五、小结

「饼图标签 hover 后 title 消失」看似玄学,本质是 ECharts 标签防重叠布局 + emphasis 状态机的一个交互陷阱:

防重叠布局在普通态把某些标签(行)判为「隐藏」;
emphasis 态默认沿用这个隐藏状态,而不是因高亮而恢复;
表现为「悬浮即消失,移开即恢复」。

修复只有一步:emphasis.label.show: true + emphasis.labelLine.show: true ,把显示权从「沿用隐藏」手里夺回来。记住「emphasis 不自动继承普通态的显示设置」,这个坑就不会再踩。