1. 为什么画水平直线要优先用markLine而不是graphic手绘先聊一个常见的场景。之前有人问我ECharts里要加一条水平直线是不是用graphic组件画个矩形或者线段就行我说别急你要是只画一条静态线graphic确实能凑合但这属于“用错了轮子”。ECharts本身有专门做这件事的配置项叫markLine标准线/标记线。它就是给图表加参考线用的水平直线、垂直直线、平均值线、警戒线、目标线都是它的本职工作。很多人第一反应去翻graphic的文档是因为不知道markLine的存在或者只知道它能显示平均值不知道还能手动指定任意数值。这两者的核心区别在于坐标系感知能力。markLine是“认识”坐标轴的你给它一个yAxis: 200它就知道这是y轴上数值200的位置然后精确画在对应的网格线上。坐标轴范围变了、数据缩放窗口变了、图表resize了它都会自动重新计算位置。而graphic组件是纯粹的像素级绘制你得自己拿scale去算200在屏幕上的像素坐标窗口一变、数据一刷新位置就全错了。我见过不少项目早期用graphic画线后来加了数据缩放功能标准线就漂移了最后不得不返工换成markLine。所以如果你还没开始写或者正准备写直接选markLine就对了。markLine也不是只能画水平直线。它和数据绑定后能做的事情很广水平直线对应yAxis坐标值这是本文主角垂直直线对应xAxis坐标值通常用来标关键时间点平均值、最大值、最小值、中位数通过type字段自动计算区间线段比如今天的零点到明天的零点画一条区间标注线。这里放一张对比表格更直观对比项markLinegraphic坐标感知跟随坐标系自动定位纯像素定位需手动换算数据联动数据变化时自动响应需要手动触发重绘逻辑平均值/最大最小值原生支持需要自己算好再传值标签显示内置label支持formatter需要额外写Text组件动画与高亮跟随系列动画与emphasis全部自己实现学习成本一个配置项需要理解graphic元素模型所以结论很简单给echarts加水平直线或者标准线首选markLine。这一点先明确后面所有内容都建立在这个选型上。2. 从零搭建markLine最简配置与核心配置项拆解2.1 一个最小可用的示例先看一个最直白的例子。假设现在有一张折线图我想在y轴数值150的位置加一条水平标准线代码如下const chart echarts.init(document.getElementById(main)); chart.setOption({ xAxis: { type: category, data: [周一, 周二, 周三, 周四, 周五, 周六, 周日] }, yAxis: { type: value, name: 销量 }, series: [{ type: line, data: [120, 200, 150, 80, 170, 110, 90], markLine: { symbol: none, data: [ { yAxis: 150, name: 目标线 } ] } }] });这一段代码跑起来120、200、150这些点构成的折线图上就会出现一条水平线与y轴150相交。注意几个关键点symbol: none是去掉线条两端默认的小箭头否则画出来的不是干净的直线而是一条带箭头的标记线data数组里放一个对象yAxis就是这条线对应的数值。有同学会问为什么不放在 series 外面因为markLine在设计上就是“属于某个系列”的。哪怕你有一百个系列也只给其中某一个系列配置了markLine那么这条线就只跟这个系列绑定。如果系列因为图例legend被隐藏线也会跟着消失这一点后面细说。2.2 data数组的两种核心写法markLine.data是整条线的灵魂它支持两种写法。第一种是指定具体的坐标值也就是本文主角水平直线/标准线data: [ { yAxis: 150, name: 目标线 }, { yAxis: 300, name: 警戒线 } ]一条横线就是一个对象对象里写yAxis值。如果想画垂直的线就写xAxis。如果想画一条带起止的线段可以直接传二维数组data: [ [ { xAxis: 周一, yAxis: 120 }, { xAxis: 周五, yAxis: 200 } ] ]不过这种画法更偏向区域标记日常画水平直线用得少感兴趣的可以先了解一下。第二种是使用type字段让ECharts自动计算data: [ { type: average, name: 平均线 }, { type: max, name: 最高点 }, { type: min, name: 最低点 } ]type支持四类值average平均值、min最小值、max最大值、median中位数。这四个值不需要你预先算好ECharts会根据当前系列的数据自动计算。生产环境里用得最多的是average比如给销售数据加一条“月均线”。2.3 lineStyle与label让线不再是光秃秃的线默认的markLine是一条红色实线label显示“目标线: 150”这样的文案。你要是在大屏项目里直接这么用视觉上会特别突兀。所以几乎每个项目都得重新定制样式。先看lineStyle控制线的颜色、粗细、虚实markLine: { symbol: none, lineStyle: { color: #fa8c16, type: dashed, width: 2 }, data: [{ yAxis: 150, name: 目标线 }] }再看label控制标签文字的位置和格式markLine: { symbol: none, label: { formatter: {b}{c}, position: insideEndTop, color: #fa8c16, fontSize: 12 }, data: [{ yAxis: 150, name: 目标线 }] }formatter里的{b}是name字段的值{c}是当前坐标值。如果name没启用就只剩{c}。position控制标签在线上的哪个位置水平线一般用insideEndTop线末端的上方或者start起始处别硬背自己多试几个值就知道区别了。这条线如果希望在数据提示tooltip里被点中还可以打开triggerEvent: true但要留意它会影响鼠标交互后面会专门讲。3. 五种高频业务场景平均值线、预警阈值线、目标线、双Y轴线与多系列线的落地写法3.1 平均值线最容易也要注意精度这是markLine最常见的用法给数据加一条“均值参考线”。一般写起来就是一行配置markLine: { symbol: none, data: [ { type: average, name: 月均 } ] }但有三个细节需要留意。第一average算出来的值可能有很多小数位比如销量均值是178.3333标签里显示一长串肯定不行你需要设置precisiondata: [ { type: average, name: 月均, precision: 2 } ]precision专门控制markLine计算型标签的小数位数对average、max、min都生效。第二average计算的是“当前系列的数据”不是整个图表所有系列。如果图上有多条折线你想画的是这些折线的整体平均值就得自己先算出均值然后用{ yAxis: 180 }直接指定。第三如果这个系列有stack叠加堆叠图average算的是堆叠后的总和而不是单个数据点这个在堆叠面积图场景很容易踩坑。3.2 预警阈值线变色与文案的规范化预警场景在工业监控、运维大屏中非常常见。比如CPU使用率超过85%就要告警那就在85%这个位置画一条红色虚线并加上“告警线”文字。我的做法是把它封装成一个函数方便多处复用function createThresholdLine(value, name, color #f5222d) { return { name, yAxis: value, lineStyle: { color, type: dashed, width: 2 }, label: { formatter: ${name}{c}, position: insideEndTop, color } }; } // 使用 markLine: { symbol: none, data: [ createThresholdLine(85, CPU告警线), createThresholdLine(60, CPU预警线, #faad14) ] }这样一条预警线、一条告警线颜色不同、数值不同但配置逻辑统一。生产上我一般还会把线的显示/隐藏控制交给系列来控制配合legend字段即可。3.3 目标完成线结合动态数据的设置如果业务需求是“这个月目标销售额是100万每天更新数据看有没有达到目标”那markLine的值就是从接口或全局变量里拿到的比如const targetValue getTargetFromServer(); // 比如 1000000 chart.setOption({ series: [{ type: bar, data: dailySalesData, markLine: { symbol: none, data: [ { yAxis: targetValue, name: 月度目标 } ], lineStyle: { color: #389e0d, width: 2 }, label: { formatter: 目标{c}, position: middle } } }] });这里有个规范要点markLine的data你可以随时通过setOption覆盖。数据更新后只要重新调用setOption新的标准线数值就会生效。不需要你手动去“删除旧线再画新线”直接覆盖即可。3.4 双Y轴场景markLine不能跨轴要用辅助series这个坑我踩过不少次。当图有左右两个y轴时一个series默认只认一个y轴。如果你想在右侧y轴画一条标准线直接在这个series的markLine里写yAxis: 200这个200是左侧轴的数值它不会聪明地自动去右侧找200。解决办法有两种。一种是你清楚知道右侧轴的范围手动做换算但这样太脆弱。更推荐的做法是创建一个只有markLine的空series让它绑定目标y轴。series: [ { name: 销量, type: bar, yAxisIndex: 0, data: [120, 200, 150, 80] }, { name: 利润率, type: line, yAxisIndex: 1, data: [12, 18, 15, 10] }, { // 辅助系列只为在右侧y轴画线不显示实际数据 name: 利润率目标, type: line, yAxisIndex: 1, data: [], markLine: { symbol: none, data: [{ yAxis: 15, name: 利润率目标 }], lineStyle: { color: #722ed1 }, label: { formatter: 目标率{c}%, position: insideEndTop } } } ]这个空series没有数据不会画线、不会出点但它绑定了yAxisIndex: 1所以里面的markLine能正确落在右侧y轴。项目里我经常把这个辅助series的showSymbol设为false、数据设为[]减少毫无意义的渲染消耗。3.5 多系列图表markLine跟着哪个series走图上有一堆系列时你就要想清楚这条线是“全局标准线”还是“某个系列的线”。如果是全局的比如“整体目标线”放哪个series里无所谓因为数值是坐标轴级的线条位置只取决于yAxis的值。如果是“某个系列的均值线”那就只能放那个系列上且平均值只算那个系列的数据。有一种做法是把markLine放在一个隐藏series里让它作为“全局标准线容器”{ name: 标准线容器, type: line, data: [], xAxisIndex: 0, yAxisIndex: 0, markLine: { ... } }这样做的好处是无论其他系列怎么增删这条线都保持稳定不会因为图例切换而消失。4. 动态数据下markLine的联动更新与适配4.1 setOption更新标准线覆盖的时机在真实项目里标准线的值很少是一成不变的。比如每天更新的“今日目标”、每小时的“P99延迟基线”都需要随接口数据刷新。更新markLine最简单的方式就是重新设置series里的markLine// 第一次渲染 chart.setOption({ series: [{ type: line, data: currentData, markLine: { data: [{ yAxis: 100, name: 昨日平均 }] } }] }); // 10秒后数据刷新 chart.setOption({ series: [{ type: line, data: nextData, markLine: { data: [{ yAxis: nextAvg, name: 昨日平均 }] } }] });这里有一个隐藏规则要记住如果你的series之前的markLine配置里有多个data项而新配置里只有一个data项那么setOption默认是“合并”而不是“替换”的。某些情况下旧的data项可能残留导致线上有两条标准线。为了彻底清掉旧的最稳妥的做法是chart.setOption({ series: [{ markLine: { data: [newLine] } }] }, { replaceMerge: [series] });replaceMerge: [series]会强制用新series配置替换旧的而不是合并。这在动态切换指标、指标数量变化不定的场景下尤其有用。4.2 数据窗口变化后保证markLine精度有时间序列图表上会有dataZoom用户缩放后坐标轴范围发生变化。markLine的值本身是数据值不是像素值所以它会自动跟着缩放不需要手动额外处理。但有一个细节可能会坑到人如果markLine的数值在缩放后的数据窗口里不显示比如你缩放后的某段时间数据的最大值是90而你画了一条200的线这条线依然会显示在图表里只是可能顶到图表的可视区域边缘甚至裁切掉。这不算bug是语义问题标准线不应该随数据窗口消失它代表的是一个恒定参考值。如果业务上你希望它跟随数据窗口变化比如只显示当前窗口的平均值那就需要在更新dataZoom时重新计算并setOption把markLine的值改成窗口内数据的平均值。我在实际开发里有这样一个模式chart.on(datazoom, function () { const windowData getWindowData(); // 获取当前窗口数据 const avg computeAverage(windowData); chart.setOption({ series: [{ markLine: { data: [{ yAxis: avg, name: 窗口均值 }] } }] }); });4.3 大屏适配与resize处理markLine在图表resize后会自动重新计算位置但如果你在大屏项目里用rem统一缩放label的文字大小、symbol的大小如果没设none可能会显得不协调。因为markLine的字体大小不会自动跟着rem走它主要是由ECharts内部渲染。我的处理方法是把markLine的label.fontSize、lineStyle.width这些值也纳入统一的适配函数在resize的时候重设。比如function updateMarkLineStyle(chart) { const fontSize window.innerWidth * 0.008; // 按屏幕宽度算字号 chart.setOption({ series: [{ markLine: { label: { fontSize }, lineStyle: { width: Math.max(1, window.innerWidth * 0.0008) } } }] }); } window.addEventListener(resize, function () { updateMarkLineStyle(chart); chart.resize(); });注意不要每次resize都把整个markLine.data重设一遍尽量只重设样式字段减少性能消耗。如果你发现大屏适配后markLine标签错位、字号异常多数是resize时没有同步更新这些样式导致。5. 想要一条“带细节的线”标签、样式与交互打磨5.1 label的formatter与rich textmarkLine的label最实用的就是自定义formatter。它支持字符串模板和回调函数两种写法。字符串模板最常用label: { formatter: {b}\n目标值{c}, position: insideEndTop }\n可以实现换行适合显示多行标签信息。{b}是name{c}是坐标值。如果你的图表有多个y轴{c}默认显示的是markLine所在坐标轴的数值不会自动加单位所以业务上往往需要在name里带上单位比如“告警线%”。如果需要完全自定义排版用回调函数label: { formatter(params) { return 目标 ${params.value}达成率 ${(params.value / target * 100).toFixed(1)}%; } }回调函数的params.value就是当前线对应的数值你可以拿它做各种计算。配合ECharts的rich富文本样式可以做到一行文字里不同颜色、不同字号label: { formatter: {nameStyle|目标线} {valueStyle|150}, rich: { nameStyle: { color: #999, fontSize: 12 }, valueStyle: { color: #fa8c16, fontSize: 14, fontWeight: bold } } }5.2 线端符号symbol什么时候该去掉什么时候该保留markLine的symbol控制线两端的图形标记默认是箭头end这在描述“达到某个目标/阈值”时很有用。比如库存低于警戒线时箭头指向当前值。但在大多数水平标准线场景里去掉箭头更干净symbol: none如果你希望箭头保留又想让箭头看起来小一些symbol: [none, arrow], symbolSize: [0, 8]symbol为数组时第一个元素是起点标记第二个是终点标记。水平直线一般起点设为none终点视业务需求设arrow或none。symbolSize同理分别是起点和终点的尺寸。我在项目里的经验是代表“不可超出的上限”用实线箭头代表“参考均值或目标”用虚线无箭头这样用户只看线型就能感知语义。5.3 交互点击标准线弹出详情markLine默认不响应鼠标事件但你可以通过设置triggerEvent: true让它支持点击、悬浮等行为markLine: { triggerEvent: true, // 关键打开事件触发 data: [{ yAxis: 150, name: 目标线 }] } chart.on(click, function (params) { if (params.componentType markLine) { console.log(点击了标准线, params.name); // 这里可以打开弹窗、跳转详情 } });注意开启后标准线会拦截一部分鼠标事件如果线正好压在柱状图或折线图数据点上可能会影响原有数据点的点击操作。所以要不要开triggerEvent要想清楚业务主次。5.4 emphasis与淡出视觉高亮交互高亮交互属于加分项。当鼠标悬浮到数据点上时可以让标准线变暗一些或者反过来悬浮到线上时高亮markLine: { data: [{ yAxis: 150, name: 目标线 }], emphasis: { lineStyle: { width: 4, color: #fa541c }, label: { fontWeight: bold } } }如果你的页面有夜间模式、主题切换还可以用这种方式同步调整线的颜色。6. 踩坑复盘markLine在真实项目里的几个隐蔽问题6.1 标准线不显示八成是这五个原因markLine“不显示”是我被问得最多的问题。一条条排查基本不离这五类数值超出坐标轴范围。比如数据最大100你画了yAxis: 200那线可能在图表可视范围外面。检查y轴的min/max是否包含该值。markLine放在了错误的层级。markLine一定在series内部的markLine字段下不是series.markLine一定是series.markLine写错位置就报错或者不渲染。有些新手会写成option.markLine这就完全错了。被其他元素遮挡。如果图上叠加了面积图阴影、辅助背景色线可能被盖住了。可以调高线的z-level或换一种更鲜明的颜色。markLine没有全局的zAdjust但可以通过lineStyle的shadowBlur或透明度处理层级感。图例把对应系列隐藏了。如果线所在的series在legend中被切换隐藏线自然也不显示。确认图例状态。symbol和lineStyle配合让线几乎不可见。如果线的颜色太浅、宽度太小或者symbol设置成无箭头但lineStyle.color为透明肉眼几乎看不到。用默认配置先确认渲染出来再逐步改样式。排查时我的习惯是先把markLine配置简化到最低限度markLine: { data: [{ yAxis: 150 }] }如果这样能看到线那问题就在样式或交互配置上如果还看不到那就是数据范围或坐标轴的问题。6.2 average的结果和你预期不一致type: average虽然方便但它算的是“当前series当前data数组”的平均值。如果数据经过stack堆叠、多个series合并或者series.data里有null值平均值会和你手算的“业务平均值”不一致。比如有一个系列的数据是[120, null, 150, 80, null, 110]ECharts在计算average时会把这些null算进去吗真实行为是null会被跳过average是有效值的平均。如果你的业务算平均值时把null当成0那这俩结果就不一样了。解决思路很简单不要在业务精度要求高的场景直接依赖type: average自己用reduce或lodash计算均值然后通过{ yAxis: yourCalculatedAvg }传进去这样逻辑可解释、可测试、可复用。6.3 多Y轴情况下markLine“画反了”前面提过双Y轴场景。这里再补充一个更隐蔽的情况如果你的图有多个series且它们绑定的yAxisIndex不同而markLine放在了其中某一个series上那么这个markLine的yAxis数值是相对于该series对应的坐标轴的。但你心里可能还想着“这个数值应该属于另一个轴”这就导致看起来“画反了”。本质原因是markLine的坐标值不是“图表全局坐标”而是“所在series的坐标系坐标”。搞懂这一点多Y轴场景就不会再犯迷糊。解决方式有两种一是把markLine放到正确的series下二是用辅助空series前文已写过精确绑定目标y轴。6.4 tooltip与markLine的视觉冲突markLine本身不参与tooltip的默认展示但它的label如果设置了{c}而且数据是百分比、金额等默认显示会缺少单位。这在业务上其实是一个“显示不完整”的问题容易被忽略但影响专业感。另外如果markLine开启triggerEvent在图上触发tooltip时鼠标经过标准线会有点击事件的闪烁感。我的建议是如果没有必要保持silent: true默认就是silent让标准线不参与鼠标事件。只有需要点击跳转时再显示开启。6.5 rem适配与markLine的标签位置偏移这个问题前面也提到过。这里补一个具体的现象大屏自适应后图表的坐标轴、柱子、线条都正确缩放但是markLine的label文字跑到了线下面去甚至超出边界。这是因为markLine的labelposition是相对于线的锚点定位的当图表缩放后锚点变了而fontSize没变相对位置的视觉比例就变了。解决办法除了前文说的动态调整fontSize之外还有一种技巧是设置label.distance控制标签与线的距离label: { distance: [0, -8], // 标签在线正上方8像素 position: insideEndTop }distance在不同position下的含义不同最稳定的还是position: insideEndTop搭配distance负值让文字贴线显示。大屏项目里我一般建议先在最小分辨率、最大分辨率各测一遍确认标签不溢出再交付。最后聊点个人体会markLine这个功能表面上就一个配置项但真正用好的关键不在API而在于理解它的定位它是坐标系之子不是纯绘图的工具。画水平直线、标准线这件事凡是需要在坐标上有意义地展示参考信息都应该交给markLine而不是拿着graphic硬画。我在项目里踩过的最大的坑就是早期没想清楚这条线的“归属”把它放在了一个会随图例消失的series上结果用户一关图例预警线也没了。后来改用辅助series承载全局标准线这个问题就再也没出现过。所以我的建议是接到需求先问自己三句话这条线是全局的还是局部的它跟随哪个轴它的值会不会动态变化把这三个问题想清楚写配置基本不会错。如果你手头有现成的ECharts页面建议直接打开控制台把上面的最简配置粘进去跑一遍再逐步加需求你会发现markLine的掌控感一次比一次强。