ECharts饼图标签消失之谜：从避让机制到配置实战

标签明明显示出来了，小扇区的文字却消失，这事我印象太深了。当时在做一个数据报表，饼图里 18 个类目，第一项占了 43%，标签正常，到第 6 项以后全部不到 3%，页面上只剩几根孤零零的引线，文字全没了。老板第一时间质疑是不是控件出 bug 了。检查了一遍配置，label.show 确实开着，数据也没问题，最后定位到根本不是配置写错，而是 ECharts 的 label 有自己的“考勤逻辑”——一个标签最终能不能被画出来，不只看 show，还要过一遍内部的布局避让算法。这篇文章会把这个问题彻底拆开：标签为什么会消失、有哪些配置能强制显示、什么时候该设置显示阈值、以及标签藏起来之后怎么让信息不丢，最后给一套可以直接抄走的完整配置和踩坑清单。适合刚接触 ECharts 时被这个问题卡住的人，也适合想让落地图表更规范的前端和数据可视化开发者。

1. 标签明明设置了 show: true，为什么小扇区还是不显示

1.1 先复现一个典型场景

要理解这个问题，先复现现象。下面是当时线上图表精简后的配置：

const option = { tooltip: { trigger: 'item' }, series: [{ type: 'pie', radius: ['40%', '70%'], label: { show: true, formatter: '{b} {d}%' }, data: [ { name: '类目01', value: 4320 }, { name: '类目02', value: 1890 }, { name: '类目03', value: 1560 }, { name: '类目04', value: 1120 }, { name: '类目05', value: 860 }, { name: '类目06', value: 520 }, { name: '类目07', value: 310 }, { name: '类目08', value: 180 }, { name: '类目09', value: 90 }, { name: '类目10', value: 50 } ] }] };

用 ECharts 5.4.x 跑这段代码，现象很直接：类目 01 到类目 05 的标签能正常显示，类目 06 开始，标签和引线都消失在图上。如果用官方默认配置，表现也差不多。这里的关键点在于，从代码上看我们没有做任何“禁止显示”的设置，为什么图表自己就把标签吞了。

1.2 show: true 只是“允许显示”，不等于“一定会显示”

很多人的第一反应是怀疑 label.show 是不是没有生效。实际上它生效了，但 label 的渲染过程有两道工序：配置声明阶段和布局计算阶段。show: true 属于配置声明阶段，它表达的意思是“这个标签允许被画出来”，但最终能不能真正落在画布上，要等布局计算阶段结束。ECharts 5.x 在系列渲染前会跑一个 labelLayout 生命周期，专门负责计算每个标签的位置、判断标签之间是否会互相遮挡、以及执行避让和隐藏策略。这才是决定标签生死的第二道关口。

可以理解成餐厅里服务员手里有一份预约名单，名单上的人都“允许就餐”，但餐厅座位就这么多。大桌客人优先安排，小桌客人只能在外围等。label.show: true 就是“名字在名单上”，而小扇区的标签就是那些座位不够时被放弃的小桌客人。

再看一个容易混淆的细节：ECharts 图表系列的 label 和 labelLine（引导线）是绑定的。当布局算法决定某个标签不可见时，引线也不会画出来。这也是为什么在前面复现里，小扇区连引线都看不到，而不是“文字没了，线还在”。

1.3 背后真正起作用的三个机制

结合源码和实际排查，让标签消失的机制主要有三个。

第一个是避让算法。ECharts 4.x 时代饼图就有一个 avoidLabelOverlap 配置，默认开启，作用是调整标签坐标，尽量避免文字互相遮盖。这个配置在 5.x 里仍然存在，但标签布局已经被整合到了更通用的 labelLayout 体系里。

第二个是 labelLayout.hideOverlap，ECharts 5.2 开始支持。当设置为 true 时，布局阶段如果检测到某个标签与已经绘制出来的标签存在重叠区域，就会直接隐藏新来的这个标签。这个机制对所有系列都生效，不是饼图独有，但饼图的小标签最容易被它“误伤”。

第三个是 minShowLabelAngle，这是一个专门针对扇区角度的阈值配置。如果扇区角度小于设置值，标签和引线直接不输出。后面会专门讲它。

生活化一点说，这三个机制加在一起，相当于给每个标签设了三道安检。你要显示的标签得同时通过三道门：位置不能和别的标签打架、重叠时要有位置给它让、扇区角度还得够大。小扇区的标签往往三道门全卡住，看起来就像“莫名消失”。

2. 强制显示标签：从 position、formatter 到 hideOverlap

2.1 position: inside 对小扇区更友好，但防御姿势要做足

如果想要小扇区标签也显示出来，最容易想到的办法是关掉隐藏逻辑。但关掉之前，先考虑换个位置。

饼图标签默认的 position 是 outside，也就是标签放在扇区外侧，通过引线连接。这种方式的问题是：外侧空间是共享的，标签越多、扇区越小，越容易相互重叠。两个标签一重叠，hideOverlap 就直接把后来的那个隐藏了。

把 position 改成 inside 后，标签画在扇区内部，原本的“外部空间竞争”问题就不存在了。但新的问题又来了：小扇区的面积不够大，文字放不进扇形区域。实测下来，配合这几个配置能让 inside 模式更可用：

label: { show: true, position: 'inside', fontSize: 12, color: '#fff', // 宽度设置后 overflow 才会生效 width: 60, overflow: 'break', lineHeight: 16 }

重点是 width 和 overflow。ECharts 的标签默认是可以超出扇区边界的，如果不设置 width，超过扇区宽度的文字会直接溢出，绘制效果很难看。设置了 width 之后，配合 overflow: 'break'（按词换行）或者 overflow: 'truncate'（截断加省略号），文字能在有限空间里展示出来。

不过要泼一盆冷水：inside 模式比较适合 5、6 个扇区以内的饼图。如果类目一多，小扇区被压缩到只有几度，哪怕文字折行也放不下。到时候标签之间又会互相遮挡，只是遮挡的位置从图外转移到了图内。

2.2 formatter 函数：按占比动态决定要不要输出标签

比硬显示更可控的方式，是用 formatter 函数自己控制标签的“生死”。ECharts 的 label.formatter 支持函数，函数里能拿到当前数据项的 percent 字段，按百分比做阈值判断：

label: { show: true, // 模板字符串只能做展示，做不了条件判断 // 所以这里必须用函数 formatter: function (params) { // params.percent 是浮点数，比如 2.7777777777777777 if (params.percent < 3) { return ''; } return params.name + ' ' + params.percent.toFixed(1) + '%'; } }

这里有一个细节：percent 字段是浮点数，直接拼接容易出现一长串小数，所以要用 toFixed(1) 统一格式。阈值取多少，根据业务要求来，常见的有 2%、3%、5%。这种做法的好处是，显示逻辑完全由业务方掌控，阈值清晰，不受角度和坐标计算影响。

但要注意，formatter 返回空字符串时，标签虽然不显示了，引导线 labelLine 在部分版本里依然会保留。这时候图上会有一根引线孤零零悬着，指向一个空白位置，视觉上很奇怪。处理方式是给 labelLine 单独做判断，或者干脆在标签过滤掉的场景里全局关闭 labelLine：

labelLine: { show: true }

如果整体标签密度高，建议直接设 labelLine.show 为 false，只保留纯文本。否则引线互相交叉，图会显得很脏。

2.3 关闭 hideOverlap：能显示，但标签会叠成花

还有一个更“暴力”的选项：直接把 labelLayout.hideOverlap 关闭。

labelLayout: { hideOverlap: false }

这样布局阶段就不会因为标签重叠而隐藏新标签，所有 label 都保留。实测下来，当扇区只有三四个时，这个配置很安全，标签都能正常显示。但当类目达到 10 个以上，尤其是多个小扇区挤在一起时，标签就会大面积重叠，文字互相覆盖，图表基本没法看。

所以这个配置只建议在类目数很少且确实需要所有标签都可见的时候使用。不要把它当成“解决小标签不显示”的万能药——它解决的是“看不到”，解决不了“看得到但看不清”。

3. minShowLabelAngle 与 minAngle：显示阈值和角度下限的边界

3.1 minShowLabelAngle：按角度过滤标签的正确姿势

如果希望“占比太小的就不显示标签”，最正规的配置是 minShowLabelAngle。它写在 series 层级下，和 label 平级：

series: [{ type: 'pie', minShowLabelAngle: 10, label: { show: true }, data: [/* ... */] }]

minShowLabelAngle 的含义是：扇区角度小于设定值的，就不展示标签和引线。默认是 0，也就是不限制。这个值和“占比”有个换算关系，一个圆形总共 360 度，所以：

这个配置比 formatter 做阈值更方便的一点是：它对 label 和 labelLine 是统一生效的，不会出现“标签没了但引线还在”的情况。如果数据里长尾项很多，比如几十个 1% 以下的类目，设一个 minShowLabelAngle 就能让图上只保留大块头的标签，其余自动清理掉。

根据实际使用经验，一般设 5 到 15 之间比较合理。低于 5 度时，两个相邻标签在视觉上已经贴得很近了，保留意义不大。

3.2 minAngle：把小扇区“撑大”，带来的视觉失真不可忽视

minAngle 和 minShowLabelAngle 名字很像，但作用完全不同。minAngle 不是控制标签显示，而是控制扇区的最小绘制角度。当一个扇区实际角度小于 minAngle 时，ECharts 会把它强行绘制成 minAngle 那么大：

series: [{ type: 'pie', minAngle: 5, data: [/* ... */] }]

这样做的结果是什么？假设真实数据里有一个值只占 1%，对应角度 3.6 度。设置 minAngle: 5 后，这个扇区在图上会以 5 度显示，视觉上比实际数据“胖”了差不多 40%。与此同时，其他所有扇区的角度都会被等比例压缩，以保证整个饼图仍然是 360 度。这样读者看到的大扇区占比会变小，小扇区占比会明显虚高，饼图的数值表达不够准确。

还有一个容易踩的隐藏坑：minAngle 会影响 minShowLabelAngle 的判断。因为 minAngle 先把扇区撑大了，后续再用 minShowLabelAngle 判断时，按的是撑大后的角度。一个真实占比只有 2% 的扇区，设了 minAngle: 10 后角度变大，结果 minShowLabelAngle 设成 8 时，它的标签居然能显示出来。如果业务要求“小于 2% 的项不要出标签”，这种联动就会让规则失效。

所以我的建议是：minAngle 只用在“想让长尾数据显眼一点”的场景，并且一定要在 tooltip 或其他位置展示真实数值，避免读者被视觉占比误导。单纯为了显示标签，不值得动用 minAngle。因为技术上，显示标签有 formatter、minShowLabelAngle 等多种方式，但改变视觉占比这件事是全局性的，副作用太大。

3.3 边界情况与实测建议

把两个配置放在一起看，边界情况就更明显了：

• 只设 minShowLabelAngle：最安全，只过滤标签，不影响数据角度。
• 只设 minAngle：所有标签还是会按避让逻辑走，小标签可能还是看不到，但扇区被撑大。
• 两个都设：当 minAngle 撑大后的角度大于 minShowLabelAngle 时，原本被过滤的小标签会“复活”，要小心。
• minShowLabelAngle 设置过大：比如 30 度，那低于 8% 的标签全部消失，大标签也会变少，业务方可能会觉得信息太少。

给一个实际建议：如果目的是“让图干净”，优先用 minShowLabelAngle，别碰 minAngle。如果目的是“强调某个小类目”，可以在数据项里单独给那一项配置 label 和 emphasis，而不是动全局角度。

4. 标签不显示不等于信息丢失：图例、tooltip 与富文本的组合补救

4.1 让 legend 承担数值入口

标签藏起来之后，最直接的影响是读者看不到“某一块代表什么、值是多少”。这种情况下，图例 legend 是最容易利用的补救入口。ECharts 的 legend 默认只显示类目名称，但通过 formatter 函数，可以拼上数值和占比：

legend: { formatter: function (name) { const item = data.find(function (d) { return d.name === name; }); if (!item) return name; const total = data.reduce(function (sum, d) { return sum + d.value; }, 0); const percent = (item.value / total * 100).toFixed(1); return name + ' ' + item.value + ' (' + percent + '%)'; } }

这样做的好处是：小扇区虽然在图上没有标签，但图例区域依然能看到完整的名称、数值和占比。鼠标不用悬停到扇区上，信息就在眼前。对于“领导只看一眼图表”的场景，这个方案比任何复杂配置都管用。

不过要注意，legend 项的展示空间是有限的。如果数据量超过 15 项，图例会变得很长，建议配合滚动或者折叠。但至少，信息没有丢。

4.2 tooltip：把明细留给交互层

另一个天然的补救方式是 tooltip。无论标签是否显示，饼图扇区都是可交互的，鼠标悬停时 tooltip 都能正常弹出。默认情况下用 trigger: 'item' 就能显示 name、value 和百分比：

tooltip: { trigger: 'item', formatter: function (params) { return params.name + '<br/>' + '数值：' + params.value + '<br/>' + '占比：' + params.percent.toFixed(1) + '%'; } }

这里的 params.percent 和 label.formatter 里的一样，都是浮点数，需要自己格式化。把 tooltip 文案做成“名称 + 真实数值 + 占比”的格式，用户鼠标悬停在小扇区上就能看到完整信息。而且 tooltip 天然不受标签避让逻辑影响，哪怕标签隐藏了，交互信息也完整。

4.3 富文本：给重点标签加样式

前面提到 formatter 函数可以控制标签内容，其实它还能返回带样式的富文本。通过 label.rich 定义样式片段，然后 formatter 里按需组合，可以让重点标签在有限空间里突出显示：

label: { show: true, formatter: function (params) { if (params.percent < 3) return ''; // 对占比大于 10% 的重点项，用加粗和醒目的颜色 if (params.percent >= 10) { return '{strong|' + params.name + ' ' + params.percent.toFixed(1) + '%}'; } return params.name + ' ' + params.percent.toFixed(1) + '%'; }, rich: { strong: { fontSize: 14, fontWeight: 'bold', color: '#333' } } }

这种方式很适合“图表要传达重点”的场景。比如 18 个类目里真正重要的是前 3 项，其余都是长尾，那前 3 项用加粗标注，其余的隐藏或者用小字号展示，信息层次就出来了。

不过要提醒一下：富文本会增大标签的渲染体积，体积越大，越容易被避让算法隐藏。所以在标签密集的场景里，富文本样式不要堆太多，否则会出现“样式越复杂，标签越容易消失”的悖论。

4.4 emphasis 联动：平时隐藏，hover 时再显示

还有一个容易被忽略的配置：emphasis.label.show。可以设置默认 label 全部隐藏，只在 hover 到某个扇区时显示对应的标签：

label: { show: false }, emphasis: { label: { show: true, fontSize: 14, fontWeight: 'bold' } }

这种方式适合“图表默认保持纯净，用户需要时再主动查看”的场景。视觉效果很好，交互感也很强。但代价是用户如果没有 hover 的习惯，可能不会发现标签的存在。所以这个方案更适合配合 tooltip 一起用，而不是单独依赖。

5. 完整示例、参数组合与踩坑清单

5.1 一个可以直接复制的常规配置

综合前面的方案，一个比较常规、适合 8 到 15 个类目饼图的配置如下：

const data = [ { name: '类目01', value: 4320 }, { name: '类目02', value: 1890 }, { name: '类目03', value: 1560 }, { name: '类目04', value: 1120 }, { name: '类目05', value: 860 }, { name: '类目06', value: 520 }, { name: '类目07', value: 310 }, { name: '类目08', value: 180 }, { name: '类目09', value: 90 }, { name: '类目10', value: 50 } ]; const total = data.reduce((sum, d) => sum + d.value, 0); const option = { tooltip: { trigger: 'item', formatter: function (params) { return params.name + '<br/>' + '数值：' + params.value + '<br/>' + '占比：' + params.percent.toFixed(1) + '%'; } }, legend: { bottom: 0, formatter: function (name) { const item = data.find(d => d.name === name); if (!item) return name; const p = (item.value / total * 100).toFixed(1); return name + ' ' + item.value + ' (' + p + '%)'; } }, series: [{ type: 'pie', radius: ['35%', '65%'], center: ['50%', '45%'], minShowLabelAngle: 5, label: { show: true, formatter: function (params) { // 小于 3% 的项目标签不渲染 if (params.percent < 3) return ''; // 大于 10% 的重点项加粗 if (params.percent >= 10) { return '{strong|' + params.name + ' ' + params.percent.toFixed(1) + '%}'; } return params.name + ' ' + params.percent.toFixed(1) + '%'; }, rich: { strong: { fontSize: 14, fontWeight: 'bold', color: '#333' } } }, labelLine: { show: true }, data: data }] };

这个配置的做法是：用 minShowLabelAngle: 5 过滤掉角度小于 5 度（占比约 1.39%）的所有标签；再通过 formatter 把 3% 以下但有引线的项目过滤掉；让 10% 以上的重点项目用加粗富文本突出显示。所有信息都可以通过 legend 和 tooltip 查看到，图表本身则保持了相对清爽的视觉效果。

实测下来，这个配置在类目数 15 个以内时表现稳定。超过 15 个，建议再提高 minShowLabelAngle 和 formatter 的阈值。

5.2 针对不同数据规模的参数选择

不同数据规模，处理策略完全不同。给一个参考表：

其中“聚合其他”是一个在数据清洗阶段就该处理的方案，把占比小于阈值的长尾项合并为一个“其他”类目。这样饼图的数据点一下子少了很多，标签也自然能正常显示。这个方案的关键是提前和业务确认“其他”类目是否可接受，以及真实明细要怎么给用户查阅。我通常会在 tooltip 里展示聚合项下的明细列表，或者提供点击事件弹窗。

5.3 踩坑清单：这些坑我都替你们踩过了

结合多个项目的实际经验，整理一份避坑记录：

第一个坑是 minAngle 撑大扇区后的视觉失真。有一个版本上线后，业务反馈饼图里 1% 的项目看起来比实际的 3% 还粗。排查发现是某个历史同事为了保证标签显示，全局设了 minAngle: 5，真实比例被严重扭曲。后面把 minAngle 移除，改用 formatter 阈值后，视觉效果回归正常。

第二个坑是 formatter 返回空字符串后引线残留。这在 ECharts 5.2 之前的版本比较明显。如果你在 5.2 之后的版本遇到引线悬挂，可以直接给该项单独配置 labelLine.show 为 false，或者接受“标签没了但线还在”的视觉结果。实在不行，升级 ECharts 版本比绕来绕去改配置更有效。

第三个坑是 label.width 和 overflow 的组合。很多小标签看起来文字被截断了，不是数据问题，而是 label.width 设置得太窄。ECharts 在未设置 width 时，inside 标签默认允许溢出；一旦设置了 width，就得配合 overflow 决定溢出后是换行还是截断。如果希望标签自由伸展，就不要设置 width。

第四个坑是 labelLayout.hideOverlap 的全局影响。这个配置写在 series.labelLayout 下或者 option 顶层 labelLayout 下都能生效，但它不是饼图专属。如果项目里同一个 option 里还配了柱状图、折线图，开着 hideOverlap 可能会让其他系列的标签也出现“莫名隐藏”。排查问题时先检查全局配置，不要把锅都甩给饼图。

第五个坑是动画和动态数据更新后的标签跳动。当数据动态刷新时，小扇区标签的位置会因避让算法的重新计算而跳动。这个不影响显示与否，但会让视觉体验很糟糕。可以适当减少刷新频率，或者设置 animationDurationUpdate 来平滑过渡。

技术细节说完，最后补一句个人看法：在大多数业务场景里，小占比标签不显示并不是坏事。一个塞满标签的饼图，阅读效率往往比只显示大项标签的饼图低得多。真正好的做法是把信息分级：重点项在图上直接显示标签，长尾项通过图例、tooltip、下钻页面查明细。既保持了图表的可读性，又没丢掉任何数据。做可视化，懂得取舍比懂得把所有东西都塞上去更重要。