ECharts Tooltip配置详解：从基础到自定义富文本实战

1. ECharts Tooltip：数据可视化里最容易被低估的细节

做前端数据可视化这行，有个特别有意思的现象：很多开发者能花大量精力去调图表的颜色、坐标系、数据样式，却往往忽视了光标悬停在图表上时那个小小的提示框——tooltip。但恰恰是这个小东西，直接决定了用户在看图时的第一感受。

以ECharts为例，默认情况下鼠标移入折线图、柱状图或饼图的图形上，会弹出一个灰底白边的数据提示框，展示当前数据点的名称和数值。这看似“开箱即用”的功能，真正放到复杂的业务场景里，问题马上就出来了：默认tooltip只支持单一格式，当图表包含多个系列时效果还行，可一旦遇到自定义数据结构、多个维度的指标或者需要展示图片、富文本时，默认配置就完全不够用了。

这篇文章我会从实际项目出发，完整拆解ECharts tooltip从基础到进阶的配置方式，包括如何在前端代码中实现自定义格式化函数、如何利用formatter回调动态拼接HTML、如何处理样式冲突、如何应对React和Vue等主流框架下的兼容细节。无论你是刚接触ECharts的新手，还是已经在数据可视化大屏项目里折腾过一段时间的老手，这篇文章应该都能给你一些参考。

我尽量用真实的项目场景来讲，不只是贴API文档，而是告诉你什么时候用哪种写法，以及不同写法之间有哪些坑。

2. Tooltip基础配置：从默认弹窗到自定义内容的完整链路

2.1 先搞懂Tooltip触发的三种模式

在动手写自定义tooltip之前，先要把ECharts里tooltip的触发机制搞清楚。这是整个配置的基石，很多看起来“奇怪”的现象，比如tooltip不显示、显示的位置不对、多个series下显示混乱，根子都在触发模式上没选对。

ECharts的tooltip.trigger支持三种值：

• 'item'：只在鼠标悬浮到具体的数据项上时才触发。适合饼图、散点图、地图这类“点到点”的图形。
• 'axis'：鼠标在坐标轴区域内移动时触发，会显示该坐标轴刻度下所有系列的数据。适合柱状图、折线图这类有明确坐标轴的图表。
• 'none'：完全不触发tooltip，但可以在其他事件回调里手动调起tooltip。

实际项目里最常见的坑是：把折线图设置成了trigger: 'item'，结果鼠标在两个刻度之间的区域移动时tooltip完全没反应，用户以为图表坏了。其实不是坏了，是触发模式选错了。柱状图和折线图这类带坐标轴的图表，产品经理通常希望鼠标滑过整个绘图区都能同步看到所有线的数值对比，这时用axis模式才是正确选择。

还有一个容易被忽略的小细节：当图表同时包含柱状图和折线图时，trigger: 'axis'会把两个系列的数值都带到tooltip里。如果你只想让柱状图显示tooltip、折线图不显示，需要通过series.tooltip对单独的系列做覆盖。

2.2 最基础的显示逻辑：从只看数据到看懂数据结构

默认情况下，ECharts的tooltip展示的是当前悬停点的seriesName、name和value这三个字段。听起来很简单，但一旦你的数据是数组、对象或者嵌套结构，默认显示就会“翻车”。

举一个我踩过的真实例子：某个后台管理系统的数据接口返回的是一个对象数组，每个元素长这样：

{ date: '2024-06-01', pv: 1200, uv: 356, rate: 0.28 }

如果把整个对象直接丢给series的data数组，默认tooltip会直接把整个对象打印出来，页面上一大串[object Object]，用户直接傻眼。这时候就必须要用formatter来告诉ECharts：到底该展示对象的哪个字段、按什么格式展示。

基础的自定义格式有两种方式：

1. 字符串模板方式：在tooltip.formatter里写'{b}: {c}'这样的模板。
2. 回调函数方式：formatter是一个函数，接收params参数，返回字符串或者DOM节点。

这两种方式都要掌握，因为它们的适用范围完全不同。字符串模板适合快速搞定简单格式，回调函数适合处理复杂的数据结构。

2.3 字符串模板：五分钟搞定的快速格式化

字符串模板是ECharts tooltip最轻量的自定义方式，当你的数据是平平无奇的数组格式时非常好用。常用的占位符就这几个：

• {a}：系列名称，也就是series里的name字段。
• {b}：数据项名称，在柱状图里是x轴的值，在饼图里是数据项的名称。
• {c}：数据项数值。
• {d}：百分比，仅在饼图中有效，自动保留一位小数。

举个例子，一个简单的柱状图，希望tooltip显示“月份：xxx，销量：xxx件”，可以这样配置：

tooltip: { trigger: 'axis', formatter: '{b}<br/>{a}：{c}件' }

注意<br/>的使用，在字符串模板里它是唯一的换行手段。如果数据项比较多，想让它们竖着排列，用<br/>分隔即可。

字符串模板最大的局限在于：它只能按固定的位置插入数据，不能做条件判断，不能循环遍历，也不能处理富文本标签。一旦出现“根据值的大小显示不同颜色”或者“需要拼接自定义HTML结构”的需求，就得换回调函数了。

2.4 回调函数：真正实现“想怎么展示就怎么展示”

回调函数是tooltip自定义的核心，也是今天这篇文章的重头戏。它的基本用法是：

tooltip: { trigger: 'item', formatter: function(params) { return params.name + '<br/>' + params.value; } }

这里的params是一个对象，里面包含当前悬停点的全部信息。常用的属性有这些：

这些属性在自定义tooltip时非常重要。特别是params.color，在做自定义弹窗时可以直接用它来给数值左侧的小圆点上色，这样用户看一眼颜色就能对应到图表里的图形，交互体验会好很多。

回调函数返回的内容也很有讲究。返回字符串是最常见的做法，框架会直接把这个字符串当作HTML插入到tooltip的容器里。也就是说，你完全可以在返回值里拼接<div>、<span>、<img>等任意标签，甚至写内联样式。

举个稍微复杂的例子，一个双折线图，tooltip要同时展示两条线的数据，并且不同系列的数值要显示不同的颜色：

tooltip: { trigger: 'axis', formatter: function(params) { let res = '<div style="font-weight:bold;margin-bottom:5px;">' + params[0].name + '</div>'; params.forEach(function(item) { res += '<div style="color:' + item.color + ';">' + '<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:' + item.color + ';margin-right:5px;"></span>' + item.seriesName + '：' + item.value + '</div>'; }); return res; } }

这段代码最终生成的tooltip会变成：第一行是加粗的日期，下面两行分别显示两个系列的数据，每行前面有个和图表里图形颜色一致的小圆点，数值颜色也与系列颜色对应。这样用户在快速扫视时，一眼就能定位到对应哪条线。

这就是回调函数的威力：它给开发者完全的自由度，你可以用任何HTML结构去组织tooltip的内容。

3. 进阶场景：当Tooltip遇到复杂数据和富文本

3.1 处理对象数组：从[object Object]到清晰的多指标提示框

前面提到过，如果series的data项是对象，比如{name: '广州', value: [12, 25, 66]}这种结构，默认tooltip会直接显示成[object Object]，非常不友好。这时候回调函数里要用params.data来拿到原始对象，再从中提取字段。

举个例子，实际开发中常遇到一个城市销量图，数据结构是：

data: [ { name: '广州', value: 1200, target: 1000, growth: 0.2 }, { name: '深圳', value: 980, target: 900, growth: 0.08 }, // ... ]

目标是在鼠标悬浮到柱子上时，显示城市名、实际销量、目标值和增长率。formatter可以这样写：

formatter: function(params) { let d = params.data; let color = d.growth >= 0 ? '#67C23A' : '#F56C6C'; return '<div style="font-weight:bold;">' + d.name + '</div>' + '<div>实际销量：<b>' + d.value + '</b> 万件</div>' + '<div>目标值：' + d.target + ' 万件</div>' + '<div style="color:' + color + ';">同比增长：' + (d.growth * 100).toFixed(1) + '%</div>'; }

这里的关键点在于：只要通过params.data拿到的是原始对象，你就可以按照自己的业务逻辑去取数据、做计算、做条件判断。增长率是负的时候显示成红色，正的时候显示成绿色，这种动态效果在业务大屏里非常常见。

3.2 ECharts Map中Tooltip的特别处理

另一个经常遇到的问题出现在中国地图或者行政区划地图上。ECharts地图的tooltip默认只显示区域名称和value值，一旦数据里还有额外的字段，比如GDP构成、人口占比、同比增速等，就需要额外处理。

地图的tooltip比较特殊，因为hover触发方式和普通图表略有差异，鼠标在区块边缘移动时容易频繁触发和关闭。实测下来，给地图tooltip加一个小延迟效果会更好：

tooltip: { trigger: 'item', enterable: true, hideDelay: 100, formatter: function(params) { if (!params.value) return params.name; let data = params.data; return '<div style="font-weight:bold;font-size:14px;">' + params.name + '</div>' + '<div>GDP：' + data.gdp + ' 亿元</div>' + '<div>人口：' + data.population + ' 万人</div>' + '<div style="color:#409EFF;">同比增速：' + data.rate + '%</div>'; } }

这里面enterable: true很关键。它允许鼠标移入tooltip弹窗内部，配合自定义弹窗里的链接或者交互按钮使用。

如果遇到鼠标在地图上快速划过导致tooltip闪烁的问题，把hideDelay适当调大就能解决。

3.3 自定义富文本样式：图片、表格、进度条进弹窗

把回调函数用到位，tooltip里可以放很多东西。我在一个智慧园区项目里做过一个很大的tooltip弹窗，里面包含设备名称、运行状态、两天内的温度趋势、还有一张设备的实拍缩略图。用户把鼠标放在设备点位图上，就能看到完整的信息卡片。

这种效果完全不需要额外引用其他库，在ECharts的formatter里拼HTML就行。需要注意的一点是：如果tooltip内容里有比较复杂的CSS样式，比如浮动、绝对定位、弹性布局，部分老版本浏览器可能会渲染异常。稳妥的做法是尽量用内联样式，避免依赖外部的class。

实测中遇到过这样一个坑：ECharts的tooltip外层容器是有默认pointer-events: none的，如果你的弹窗内容里放了可点击的链接或按钮，必须先设置tooltip.enterable: true，否则鼠标一移向弹窗，tooltip就消失了，根本点不到里面的按钮。

另一个在数据大屏项目中经常用到的技巧是给tooltip制作带进度条的样式。其实很简单，用内联的div + width模拟进度条宽度即可：

formatter: function(params) { var percent = (params.value / total) * 100; return '<div style="width:200px;">' + '<div style="display:flex;justify-content:space-between;">' + '<span>' + params.name + '</span><span>' + percent.toFixed(1) + '%</span>' + '</div>' + '<div style="height:6px;background:#eee;border-radius:3px;margin-top:4px;">' + '<div style="height:100%;width:' + percent + '%;background:' + params.color + ';border-radius:3px;"></div>' + '</div></div>'; }

这样tooltip里会显示一个和数值匹配的彩色进度条，在大屏展示时视觉效果比纯文字好很多。

3.4 Tooltip自动换行：中文长文本不折行的解决办法

搜索热词里有一条“echarts tooltip自动换行”，这说明遇到中文长文本不换行问题的人不在少数。

默认情况下，tooltip容器是absolute定位的白底div包着一个内部div，而ECharts并没有给这个内部div设置word-break样式。英文或数字中间没有空格时浏览器默认换行逻辑很可能不生效，导致长单词或连续数字把容器撑宽，中文倒还好有标点兜底，但英文和数字很常见。

解决办法一个是在自定义tooltip时给自己拼的容器加样式：

'<div style="max-width:300px;word-break:break-all;white-space:normal;">' + longText + '</div>'

另一个简单粗暴的办法是直接改全局CSS，覆盖ECharts生成的tooltip样式。ECharts生成的tooltip内容区类名一般是div内带style样式，默认有一个white-space: nowrap。可以通过全局CSS强制覆盖，稳妥期间在自定义样式中写white-space和word-break。实测下来最靠谱的还是第一招：自己在返回值里控制容器的宽度和换行规则，因为ECharts内联样式的优先级很高，靠外部CSS覆盖很容易被压过去。

3.5 大屏适配：resolve中pxtorem对ECharts失效的根源

热搜词里有一条“pxtorem 对echarts没起到效果 vue3”，这个问题在大屏项目中我碰到过不止一次。

其实原因非常直接：ECharts实例在渲染时，tooltip的内容是通过JavaScript动态创建的元素，并且大量使用内联样式。postcss-pxtorem这类的库只能处理编译阶段构建出来的CSS文件里的px单位，而ECharts在运行时动态生成的内联px样式，构建工具根本管不到。

所以大屏适配时，建议不要在ECharts内部依赖pxtorem转换，而是做自适应时在图表外层根据设计稿比例计算一个缩放系数，整体放大缩小容器尺寸。如果是Vue3项目，常见做法是监听窗口resize事件，计算出缩放比后更新容器宽高，再用chart.resize()让ECharts重绘。

另外，ECharts的tooltip默认有个textStyle.fontSize配置，可以直接按设计稿的px值设置。如果你需要整个弹窗随大屏比例缩放，直接用rem单位设置tooltip.textStyle.fontSize是无效的，这件事我确认过，因为内联样式里它只认px合法的数值。比较省心的一套做法是：tooltip的字体大小全部也比屏宽动态计算后写入，再用tooltip.extraCssText注入额外样式。

4. 实战演示：做一个带自定义Tooltip的中国地图数据大屏

4.1 需求拆解与数据设计

大屏项目里最常见的一个场景是“中国地图 + 各省份数据”。要做的效果：鼠标悬停到某个省份上时，弹窗展示省份名称、核心指标、环比增幅，并且不同增幅区间显示不同的颜色。

先定义数据结构。一般后端返回的数据是按省份名称作为key的对象：

const rawData = { '广东': { value: 10982, growth: 0.086, rank: 1 }, '江苏': { value: 10213, growth: 0.063, rank: 2 }, '山东': { value: 7409, growth: 0.057, rank: 3 }, // ... };

做地图时，需要把name和value作为标准化字段合并到geoCoordData或者map的data里。标准做法是把数据转换成ECharts地图series所需的格式：

const mapData = Object.keys(rawData).map(function(name) { return { name: name, value: rawData[name].value, growth: rawData[name].growth, rank: rawData[name].rank }; });

4.2 地图Tooltip完整代码与样式说明

地图部分的series配置核心如下：

series: [{ type: 'map', map: 'china', roam: true, label: { show: true, fontSize: 10 }, data: mapData, tooltip: { trigger: 'item', enterable: true, hideDelay: 150, formatter: function(params) { if (!params.data) return params.name; var growth = params.data.growth; var color = growth >= 0 ? '#F56C6C' : '#67C23A'; var arrow = growth >= 0 ? '↑' : '↓'; return '<div style="min-width:180px;">' + '<div style="font-size:15px;font-weight:bold;color:#333;margin-bottom:6px;">' + params.name + '</div>' + '<div style="font-size:13px;color:#666;margin-bottom:3px;">' + '核心指标：<span style="font-weight:bold;color:#409EFF;">' + params.value + ' 万元</span>' + '</div>' + '<div style="font-size:13px;color:#666;margin-bottom:3px;">' + '排名：第 <span style="font-weight:bold;">' + params.data.rank + '</span> 位' + '</div>' + '<div style="font-size:13px;color:' + color + ';font-weight:bold;">' + '同比增长：' + arrow + ' ' + (growth * 100).toFixed(1) + '%' + '</div>' + '</div>'; } } }]

其中几个关键点：颜色区分用正绿负红的话注意国人的阅读习惯，增长用红色在中国语境下通常代表涨、用绿色代表跌，但不同公司规范可能相反；enterable: true保证多个省份数据对比时鼠标可以移入弹窗内的文本选择复制；箭头和颜色双保险，即使色盲用户也能通过箭头判断涨跌方向。

4.3 MarkPoint在Tooltip配置中的联动细节

中国地图上经常要叠加markPoint，比如把某些核心城市或者异常点标注出来。markPoint的tooltip和地图本身的tooltip是分开配置的，selector上容易被忽略。

markPoint的data项如果包含自定义字段，它也支持独立的tooltip formatter：

markPoint: { symbolSize: 8, data: [{ name: '重点关注', coord: [113.2, 23.1], value: 128, level: '高危' }], tooltip: { formatter: function(params) { return '<div>' + params.name + '</div>' + '<div>数值：' + params.value + '</div>' + '<div>等级：' + params.data.level + '</div>'; } } }

这里有个细节要提一下：markPoint默认继承series的tooltip配置，如果你用了全局tooltip的formatter，会发现markPoint的弹窗内容和普通数据点长得一模一样，看不出差异。所以针对需要特殊提示的markPoint点，务必在markPoint内部覆盖tooltip。

4.4 给Tooltip外层加自定义样式

有些情况下，ECharts默认的tooltip外层样式——白底、灰边框、默认阴影——和深色大屏的主题不搭。这时候不用憋着，ECharts允许通过extraCssText注入额外的CSS样式：

tooltip: { backgroundColor: 'rgba(255,255,255,0.95)', borderColor: '#409EFF', borderWidth: 1, padding: [12, 16], textStyle: { color: '#333', fontSize: 13 }, extraCssText: 'box-shadow: 0 6px 18px rgba(0,0,0,0.15);border-radius:6px;' }

extraCssText在深色主题里特别有用。如果你用的是玻璃拟态风格的漂亮背景、大圆角、多层阴影，都可以直接写在字符串里。需要注意的是，它只会补在tooltip的最外层容器上，无法控制内部内容的布局。

5. 多系列图表中Tooltip的联动与细节优化

5.1 Axis触发模式下多系列的展示策略

折线图上经常有两条线，比如“本月销量”和“上月销量”，这时用trigger: 'axis'就能同时展示两条线的数值，方便对比。

但多系列带来的问题是：默认情况下，ECharts会把所有系列的name和value都列出来，视觉上比较混乱。如果只想展示特定的几个系列，可以用tooltip.triggerOn或者直接在formatter里过滤：

formatter: function(params) { // params 是数组，因为trigger: axis模式下会传递所有series的数据 var filtered = params.filter(function(item) { return item.seriesName !== '隐藏系列'; }); // 继续拼接 }

这样既保留axis的触发体验，又能自由控制展示哪些系列。

5.2 Tooltip中自定义点击事件与跳转

当enterable: true时，tooltip内部就是一个普通DOM区域，可以在里面放<a>链接或者绑定事件。但要注意，直接用onclick属性绑定事件，在某些安全设置下可能会被浏览器阻止。更稳妥的方式是在ECharts初始化后，通过事件委托给文档绑定click事件，利用event.target判断是否点击了tooltip里的某个按钮。

实际大屏项目里常见需求是“点击tooltip中的详情按钮，跳转到新页面”。实现思路：

tooltip: { enterable: true, formatter: function(params) { return '<div>' + params.name + '</div>' + '<div>数值：' + params.value + '</div>' + '<div><button class="detail-btn">chartContainer.addEventListener('click', function(e) { ... });

5.3 大数据量下的Tooltip性能优化

还有一类场景值得单独提：数据量特别大的图表，比如5分钟粒度的股票分时图，一天有几百个数据点。这些图表的tooltip如果设置成triggerOn: 'mousemove'，鼠标在图上移动时会频繁触发tooltip的重绘，每秒可能几十次，性能差一点的浏览器会明显卡顿。

优化方案有两个：

• 改用triggerOn: 'click'，用户点击时再显示tooltip。
• 使用confine: true防止弹窗超出画布边缘，减少不必要的DOM计算。

另一个大赛项目里容易遇到的：大屏通常同时渲染好几个图表，每个图表tooltip都有自定义formatter。如果formatter里做了复杂的字符串拼接或计算，会影响自身性能。建议把可以提前计算好的内容在数据预处理阶段完成，formatter里只做普通字符串拼接，不做复杂循环和DOM操作。

5.4 Tooltip内容的额外字段补充

在实际的数据可视化大屏项目中，仅仅展示value往往不够。比如一个综合数据看板，用户需要看到的不只是数值，可能还有占比、同比、环比、达成率等指标。这些数据如果没有预先放在data对象里，formatter内是无法凭空拿到的。

一个常见的做法是：在给series填充数据之前，先进行一次数据预处理，把后端返回的原始RESTful数据映射成ECharts需要的结构，这同时也是做数据格式兼容、处理字段缺失的最佳时机。比如后端字段叫total_amount，前端统一映射成value，额外挂上rate、target等字段。这样tooltip的formatter里就能用params.data.rate直接取值。

6. 常见疑难杂症与排查速查表

6.1 Tooltip不显示的六种可能原因

做ECharts一年下来，遇到的tooltip不显示问题基本可以归为几类：第一类是图表容器高度为0或隐藏状态，ECharts初始化时容器没有实际尺寸，整个图表渲染不出来，tooltip自然也没有；第二类是tooltip.trigger设置错误，比如trigger: 'none'；第三类是formatter函数内部报错，有时候用了一个不存在的方法或属性，控制台报错会导致tooltip部分失效；第四类是配置了confine: false时弹窗超出边界被裁掉，看似“显示不出来”；第五类是事件被遮挡，有透明div盖在图表上方，鼠标悬浮事件根本没有触发到canvas上；第六类是系列里设置了tooltip: { show: false }覆盖了全局配置。

排查时按顺序检查：先看控制台报错，再看容器尺寸，再看配置项。

6.2 Tooltip数据为空或显示undefined

formatter里如果直接拼接params.value，而value是个对象或数组，就会出现[object Object]；如果data里某个字段缺失，就会出现undefined。建议在formatter开头做一层防御性判断：

if (!params.data) return params.name; var value = params.value || '暂无';

这行代码能避免大部分数据缺失导致的显示崩溃。

6.3 在React和Vue中的更新机制差异

React中使用ECharts时，如果state里有数据，每次更新数据都直接调用setOption，tooltip的formatter更新也会正常生效。但有一个React StrictMode下的细节：StrictMode会触发两次渲染，如果useEffect里初始化图表时没有做清理操作，可能创建两个ECharts实例，tooltip事件绑定变得混乱。解法是在cleanup函数里调用chart.dispose()。

Vue3的差异主要在数据响应式上。如果formatter里引用了响应式state里的变量，需要注意：ECharts的formatter回调是在事件触发时才执行的，Vue的响应式追踪在事件回调里依然生效。但坑点是如果state更新后你没有调用setOption更新图表，tooltip显示的仍是旧数据。

6.4 汇总：Tooltip问题排查速查表

6.5 两个容易被忽略的调试技巧

第一，ECharts有自带的调试工具：在浏览器控制台输入chart.getOption()，可以实时查看当前图表实例所有生效的配置，包括tooltip的配置是否被正确合并。这个命令非常适合排查“我明明配置了formatter，但效果没生效”的情况。

第二，formatter函数报错影响范围挺大。封装项目时建议把formatter抽取成独立函数，单独写单元测试，输入一个mock的params对象，断言输出字符串的完整性。这能大幅降低数据格式变动带来的线上风险。

7. 写在最后：Tooltip设计的一些个人体会

做数据可视化这几年，我越来越觉得tooltip不只是“一个数据弹窗”，它其实承担了数据表格的浓缩表达功能。用户第一眼看图表时看到的只是大致趋势，真正想确认“广州比深圳高多少”“这个月环比增长几个点”这些精确数值，靠的几乎全是tooltip。所以现在的项目里，我都会把tooltip当作一个交互信息卡片来设计，而不仅仅是简单地把name和value拼在一起。

在实际操作中，我一般建议团队做大屏时提前约定好tooltip的内容模板，哪个字段放第一行、哪个字段需要变色、需不需要显示排名和占比，都先列出来，再进开发。这样要比写代码时临时拼字符串清晰得多，也避免反复改版浪费工时。

最后再说一个小技巧：如果你在写formatter时拿不准某个params里到底有哪些字段，可以先用console.log(params)打印出来看一次。这个习惯帮我排查掉不少诡异的数据问题。ECharts的params结构虽然相对稳定，但不同图表类型下字段差异还是挺大的，地图的params和折线图的params字段几乎完全不同。亲眼看一下最直观，比自己猜省时间。