简介这份ECharts桑基图渐变色边示例包主要面向数据可视化与前端开发者解决如何在网页中快速搭建带流动渐变效果的桑基图适用于能源、金融、物流等行业的统计分析与大屏可视化场景。压缩包共4个文件包含2个JavaScript脚本、1个JSON数据文件与1个HTML页面整体大小仅1.01MB结构精简JS负责ECharts配置与渐变色边逻辑JSON提供节点和边的数据支撑HTML可直接运行预览并基于ECharts 5.5.0实现适配SVG渲染与常见大屏展示环境。已有168人学习下载适合希望掌握桑基图实现细节、提升图表视觉表现力的开发者参考。通过该示例可快速理解桑基图配置项、颜色渐变插值计算、数据绑定方式及交互监听思路拿到后修改数据与样式即可用于实际项目是学习ECharts高级图表与可视化美化的实用素材。1. 桑基图渐变色边为什么要自己动手改做过数据流向分析的人大概都有这个感觉默认桑基图每个节点之间就像拉了一根单色线一眼扫过去只能分辨“谁流向谁”很难看出“哪条路径更值得关注”。可一旦把这条边变成渐变色从源节点到目标节点由浅入深、由冷到暖整张图的信息密度立刻就不一样了。你第一眼看到的不是乱麻而是流量从哪来、在哪汇聚、最强的那股往哪去。这个需求在 ECharts 社区里经常被提但官方示例很少直接给可抄的代码。主要原因是桑基图的 link 样式不像折线图那样支持简单的color数组你得熟悉lineStyle.color的渐变对象写法还要处理数据格式、层级关系、曲率与透明度叠加等细节。这篇文就顺着“桑基图 → 渐变色边”这条线从基础配置讲到参数调优再给出可复用的封装方案。适合前端开发、可视化工程师以及已经用过 ECharts 饼图、地图但还没折腾过自定义边样式的同学。2. 桑基图数据结构和边样式的最小约定2.1 data、links 和 lineStyle 的关系桑基图在 ECharts 中属于series类型为sankey的系列。它与其他图表最不一样的点在于要展示的数据是“节点 节点之间的流量”所以配置项被拆成了data和links两部分。data只声明节点名称links声明从哪个节点到哪个节点、流量多少。样式上节点走itemStyle边走lineStyle而渐变色要作用在lineStyle.color上。option { series: [{ type: sankey, data: [ { name: 首页 }, { name: 列表页 }, { name: 详情页 }, { name: 支付页 } ], links: [ { source: 首页, target: 列表页, value: 100 }, { source: 列表页, target: 详情页, value: 80 }, { source: 详情页, target: 支付页, value: 50 } ], lineStyle: { color: source, opacity: 0.4, curveness: 0.5 } }] };这段代码里有一个容易混淆的点lineStyle.color默认支持source或target意味着边会直接取源节点或目标节点的颜色。这种模式适合快速成图但颜色没有过渡谈不上渐变。要实现从浅到深的渐变色边就得把color从字符串改成渐变对象。2.2 渐变对象的基本写法与适用边界ECharts 的渐变对象有两种线性渐变new echarts.graphic.LinearGradient和径向渐变new echarts.graphic.RadialGradient。桑基图的边本质上是贝塞尔曲线径向渐变很难沿着曲线方向走所以实际项目中 90% 以上用的是线性渐变。lineStyle: { color: new echarts.graphic.LinearGradient(0, 0, 1, 0, [ { offset: 0, color: #5470c6 }, { offset: 1, color: #fac858 } ]) }上面的LinearGradient构造函数有四个参数前两个是渐变起点的 x、y 坐标后两个是终点的 x、y 坐标取值范围是 0 到 1表示相对整个绘图区域的归一化坐标。colorStops数组里的offset表示渐变位置0 是起点1 是终点。这种方式对折线图、柱状图很好用因为图表区域的方向是固定的。但桑基图的边是横向或纵向流动的如果只用固定方向的渐变会出现“源节点在右边时颜色方向也是从左到右”的错位问题。2.3 边的数据流方向与渐变方向如何保持一致桑基图的标准数据链路是source指向target但节点在画布上的位置由 ECharts 的布局算法决定。默认情况下整个系列从左往右排布但如果你设置了orient: vertical就会变成从上到下。方向一变渐变也应该跟着变。通常的做法是把渐变写在回调函数里根据当前边的源节点和目标节点坐标动态创建lineStyle: { color: function(params) { var sourceNode params.data.source; var targetNode params.data.target; // 这里需要通过 series 的 data 找到节点坐标 // 简化处理时至少要知道整体方向是横向还是纵向 var gradient new echarts.graphic.LinearGradient( params.data.sourceX, params.data.sourceY, params.data.targetX, params.data.targetY, [ { offset: 0, color: sourceColor(sourceNode) }, { offset: 1, color: targetColor(targetNode) } ] ); return gradient; } }从代码可以看出渐变方向直接取自params.data里的sourceX、sourceY、targetX、targetY这些字段是 ECharts 内部在布局完成后附加到links数据上的。回调的好处是每条边都能根据实际坐标生成贴合方向的渐变不会出现颜色流向和线条走向相反的问题。3. 在 ECharts 中实现渐变色边的完整代码3.1 初始化图表与基础数据准备首先准备一个干净的 HTML 文件引入 ECharts 后初始化图表。以下代码片段基于 ECharts 5.x 版本外面套了一个容器方便后续配置。!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleECharts 桑基图渐变色边/title script srchttps://cdn.jsdelivr.net/npm/echarts5/dist/echarts.min.js/script style #chart { width: 900px; height: 600px; margin: 0 auto; } /style /head body div idchart/div script var chart echarts.init(document.getElementById(chart)); // 后续的 option 都会挂到 chart 上 /script /body /html引入 CDN 方式是快速跑通的最小步骤如果你是 Vue 3 项目直接用npm install echarts后按需引入也可以渐变对象的创建方式不变。3.2 渐变边配置回调函数里动态生成颜色接着把核心配置写完。这个示例里我设计了一条典型的页面流转链路从“首页”到“列表页”再到“详情页”“支付页”同时设置每条边颜色渐变的起止色var option { series: [{ type: sankey, data: [ { name: 首页, itemStyle: { color: #5470c6 } }, { name: 列表页, itemStyle: { color: #91cc75 } }, { name: 详情页, itemStyle: { color: #fac858 } }, { name: 支付页, itemStyle: { color: #ee6666 } } ], links: [ { source: 首页, target: 列表页, value: 100 }, { source: 首页, target: 详情页, value: 60 }, { source: 列表页, target: 详情页, value: 80 }, { source: 详情页, target: 支付页, value: 90 } ], lineStyle: { color: function(params) { var sourceColor getNodeColor(params.data.source); var targetColor getNodeColor(params.data.target); return new echarts.graphic.LinearGradient( params.data.sourceX, params.data.sourceY, params.data.targetX, params.data.targetY, [ { offset: 0, color: sourceColor }, { offset: 1, color: targetColor } ], false ); }, opacity: 0.5, curveness: 0.5, width: 2 }, emphasis: { focus: adjacency, lineStyle: { opacity: 0.8 } } }] }; function getNodeColor(nodeName) { var colorMap { 首页: #5470c6, 列表页: #91cc75, 详情页: #fac858, 支付页: #ee6666 }; return colorMap[nodeName] || #ccc; } chart.setOption(option);这段代码里的关键是lineStyle.color被写成了一个函数而不是固定字符串。ECharts 在绘制每一条边的时候会调用这个函数并把包含节点坐标和值的数据传入params。params.data.sourceX、sourceY、targetX、targetY是 ECharts 内部在开始布局后填充的坐标属性所以渐变方向天然和边的实际走向一致。getNodeColor是我自定义的函数用于根据节点名取色也可以在同一个回调里维护一个映射表。3.3 函数语法说明与注意点很多人第一次写这个回调会卡在params.data和params的层级上。params里除了data还有seriesIndex、dataIndex等字段但我们要用的坐标和源目标名字全在params.data内。如果你在links里自定义了额外字段也会出现在这里。另外LinearGradient的最后一个参数false表示渐变不需要全局坐标转换直接按传入的坐标计算。这里不设置也行但写上更明确尤其当你的图表存在多个 series 时避免坐标被统一缩放导致方向错乱。3.4 效果验收什么样的渐变算合格跑完上面的代码你应该能看到每条边从源节点颜色平滑过渡到目标节点颜色。检查三个点边在源节点一侧的颜色应该和源节点本身颜色一致或非常接近。边在目标节点一侧的颜色应该和目标节点颜色一致。边的曲线方向如果是横向从左到右那么渐变也应该从左至右而不是固定从左上到右下。满足这三点就可以说是合格的自定义渐变了。如果发现方向反了去查sourceX和sourceY的数据类型可能是某些版本中这两个字段是相对布局的百分比而不是像素值。4. 渐变色边的 3 个必调参数与视觉效果控制4.1 curveness边弯曲度如何影响渐变观感curveness是一个 0 到 1 的值默认0.5。它控制桑基图边的弯曲程度值越大边越“弓”起来。渐变本身不受curveness直接影响但因为边弯曲后同一方向的线性渐变在曲线的不同位置会有明显的颜色割裂感尤其是曲率超过 0.6 的时候边中间部位的颜色会偏离预期。参数名默认值推荐区间备注curveness0.50.3 - 0.7值越大边越弯渐变更容易看出过渡opacity0.40.3 - 0.7过高会导致节点重叠区域看不清width21 - 8会随 value 变化最小值和最大值可通过 lineStyle 的 width 函数定制如果追求渐变过渡自然我一般会把curveness控制在0.4到0.5之间。这个范围内边既保留了桑基图的流畅感又不会因为弧度太大而产生“颜色在中间断成两截”的视觉效果。4.2 opacity透明度与节点颜色叠加的权衡桑基图的边经常会出现交汇多条边重叠时如果透明度太低重叠区域会变成一团黑色块。渐变色边比纯色边更怕透明度叠加因为两条从不同方向流过来的边会在交叉处形成颜色混合。opacity: 0.3到0.5是安全区间能保留底层边的轮廓又不至于让交汇处糊成一片。这里可以配合blendMode使用。ECharts 的 series 对象支持blendMode: lighter会让重叠部分颜色相加、变亮适合深色背景上的数据大屏场景。如果你是在白色背景的报表页面保持默认的source-over更合适。4.3 width按权重缩放边宽增强渐变辨识度桑基图的边宽默认会根据value自动缩放但幅度可能不够明显。你可以用lineStyle.width的函数写法让流量更大的边更粗渐变色的展现面积也更大lineStyle: { width: function(params) { var value params.data.value; return Math.max(1, Math.log2(value 1) * 1.5); } }这个函数的逻辑是value为 0 时宽度是 1之后按对数增长避免超大流量把其他边完全挤没。由于宽度影响着渐变的视觉长度宽度越大颜色过渡越明显所以如果你希望观众注意到某条关键链路可以把它的值调大或者单独为这条边设置更宽的线宽。除了上面三个必调参数另一个容易被忽略的是nodeAlign。桑基图默认justify对齐会让边起点和终点分布比较散改成left或right后边会更集中渐变方向的一致性也更好。5. 高频排错渐变不生效、方向错乱与颜色断层5.1 渐变不生效常见原因是 color 写在了 itemStyle 里很多人在自定义了data节点的itemStyle.color之后顺手就把lineStyle.color写成了source。这个写法没有错但它会强制边直接取源节点颜色你写的LinearGradient会被忽略。检查一下lineStyle.color是否还有字符串source或target只要存在渐变就不会出现。另一个原因是 ECharts 版本。渐变对象在 ECharts 4.9 之后支持得比较稳定但部分 4.x 小版本对桑基图lineStyle.color回调的触发时机有 bug。建议直接使用 5.x 版本写法保持一致。5.2 渐变色方向错乱先看有没有设置 orient默认orient: horizontal时sourceX、sourceY是像素坐标targetX、targetY也是回调里可以根据两个点的相对位置决定渐变方向。但如果你开启了orient: vertical边的方向从左右变成上下渐变也需要从(sourceX, sourceY, targetX, targetY)改为(sourceX, sourceY, targetX, targetY)逻辑没变但坐标大小关系和视觉方向都变了。调试渐变色方向错乱最快的方法是在回调里打日志color: function(params) { console.log(params.data.source, params.data.target, params.data.sourceX, params.data.sourceY, params.data.targetX, params.data.targetY); return new echarts.graphic.LinearGradient(...); }通过日志你可以直观看到每条边的坐标走向如果横纵坐标都在变化说明节点不是严格同轴排列这时可以考虑把渐变方向改为“水平”和“垂直”混合判断但代码复杂度会上升。实际项目中绝大多数桑基图都保持水平方向所以不用过度处理。5.3 颜色断层问题多半出在透明度与曲率的叠加渐变色边中间出现一条明显的“接线”痕迹不是 ECharts 渲染 bug而是边本身就是一条贝塞尔曲线线性渐变是按直线的坐标差计算颜色插值的。曲线中间点偏离直线段越远颜色就越偏离预期表现为中间段颜色突兀。解决方法是先用curveness: 0.3测试如果断层消失说明是曲率问题。还有一种情况是opacity小于0.2时渐变的色彩对比被压平看起来像没有渐变调回0.5即可。5.4 数据量过大时渐变色边性能变差当节点超过 100 个、边超过 500 条时每个lineStyle.color回调都会创建一个新的渐变对象渲染时间会明显上升。这时候可以考虑用静态颜色映射替代动态渐变只对value排名前 N 的边做渐变其他边用color: source兜底lineStyle: { color: function(params) { if (params.data.value 10) { return source; } return createGradient(params); } }这种方式不仅保住了视觉重心还大幅减少了LinearGradient实例的创建次数交互上明显更跟手。6. 把渐变色边封装成可复用 hook直接接入 vue3 项目最后这段讲怎么把前文的配置变成一个函数让你在 Vue 3 或其他框架项目里不用每次重写一遍渐变逻辑。我一般会把“生成渐变 option”抽成独立文件输入是节点数组和链接数组输出是带渐变色边的完整配置。// useSankeyGradient.js import * as echarts from echarts; export function buildSankeyOption(data, links) { const nodeColorMap {}; data.forEach((item) { nodeColorMap[item.name] item.itemStyle?.color || #999; }); return { series: [{ type: sankey, data: data.map((item) ({ ...item })), links: links.map((item) ({ ...item })), lineStyle: { color: (params) { const sourceColor nodeColorMap[params.data.source] || #999; const targetColor nodeColorMap[params.data.target] || #999; return new echarts.graphic.LinearGradient( params.data.sourceX, params.data.sourceY, params.data.targetX, params.data.targetY, [ { offset: 0, color: sourceColor }, { offset: 1, color: targetColor } ], false ); }, opacity: 0.5, curveness: 0.45, width: 2 }, emphasis: { focus: adjacency } }] }; }使用的时候在 Vue 组件里直接调用import { buildSankeyOption } from ./useSankeyGradient; const option buildSankeyOption( [ { name: 首页, itemStyle: { color: #5470c6 } }, { name: 列表页, itemStyle: { color: #91cc75 } } ], [ { source: 首页, target: 列表页, value: 100 } ] ); myChart.setOption(option);这个封装把三个关键点都固定住了渐变方向完全由sourceX到targetX、sourceY到targetY决定不管你把图放在多宽的容器里方向都和边的走向一致。颜色映射只依赖节点的itemStyle.color你在组件里改节点颜色边的渐变色会自动跟随不用再修改边配置。params.data.value可以用来做后续的宽窄调整或高亮比如在width回调里写按需加宽的规则整个文件保持在 80 行以内很容易维护。如果你已经在用 vue3 echarts 的组合式写法只需要在onMounted里初始化图表、在watch里监听数据变化并调用setOption剩下的桑基图渐变逻辑全部走这个 hook。项目交接的时候新同事只需要知道“节点颜色决定边颜色”不需要理解LinearGradient的坐标参数维护成本会低一大截。本文还有配套的精品资源点击获取