1. 从“实心圆”到“分离扇区”为什么我们需要有间隔的饼图最近在做一个数据大屏项目客户盯着我做的饼图看了半天眉头一皱说“这图看着有点‘糊’在一块儿了能不能让这几块分开点看得更清楚” 这个需求听起来简单不就是让饼图的几个扇形之间有点空隙嘛。但当我打开 ECharts 的官方文档在series.pie的配置项里翻来找去却发现并没有一个直接的gap或者separator参数。这让我意识到这个看似简单的“饼图中间有间隔”效果其实是一个典型的“文档里没明说但社区里高频讨论”的实战技巧。在数据可视化中饼图或环形图的核心价值在于展示部分与整体的比例关系。然而传统的实心相连饼图在处理颜色相近的扇区或者扇区角度非常小时确实存在视觉区分度不足的问题。尤其是在大屏展示、移动端小屏或印刷材料中这种“糊成一团”的观感会严重影响信息的有效传递。给扇区之间增加间隔就像在排版中增加行间距能显著提升图表的可读性和美观度。它通过物理分隔来强调每个数据部分的独立性让观众的视线能更轻松地在不同扇区之间切换和聚焦。从技术实现角度看ECharts 本身并未将“扇区间隔”作为一个基础特性提供这恰恰给了开发者发挥创意的空间。实现这个效果本质上是对饼图系列中每个数据项series.data的视觉元素进行精细化控制。本文将基于最新的 ECharts 5.x 版本为你彻底拆解三种主流且稳定的实现方案并深入探讨其背后的原理、适用场景以及那些官方手册里不会写的“坑”。2. 方案一利用itemStyle.borderWidth与borderColor模拟间隔这是实现饼图间隔效果最经典、最直观也是兼容性最好的方法。其核心思路非常巧妙为每个扇区添加一个与背景色相同的粗边框利用边框来“挤占”并遮盖掉扇区之间的连接部分从而在视觉上创造出间隔的效果。2.1 核心配置与原理拆解这个方案主要依赖series.pie.itemStyle下的borderWidth和borderColor两个属性。option { series: [{ type: pie, radius: 50%, data: [ {value: 335, name: 直接访问}, {value: 310, name: 邮件营销}, {value: 234, name: 联盟广告}, {value: 135, name: 视频广告}, {value: 1548, name: 搜索引擎} ], itemStyle: { borderWidth: 5, // 关键边框宽度 borderColor: #fff // 关键边框颜色通常设置为背景色 } }] };原理分析视觉欺骗当我们将borderColor设置为与图表容器背景色例如白色#fff一致时这个边框在视觉上就“消失”了因为它融入了背景。空间挤占borderWidth定义的边框是从扇区路径的内外两侧同时延伸的。一个5px的边框会在扇区边缘的内外各占据2.5px具体算法可能因渲染引擎略有差异但概念如此。正是这向“内部”延伸的部分覆盖了原本扇区与扇区紧邻的边缘区域。间隔形成两个相邻的扇区各自都有5px的“隐形”边框。它们相邻的边缘被各自的边框覆盖中间就自然留下了一道大约5px * 2 10px宽度的、与背景色相同的缝隙这就是我们看到的“间隔”。2.2 参数计算与适配经验这里有一个非常重要的细节你设置的borderWidth值并不直接等于最终视觉上的间隔宽度。视觉间隔宽度大约是borderWidth的两倍。如果你希望间隔看起来是10px那么borderWidth设置为5px左右是一个不错的起点。但是这个比例并非绝对。它受到radius饼图半径的影响。在一个半径很大的饼图上5px的边框可能显得间隔很细在一个半径很小的饼图比如仪表盘内的微型饼图上同样的5px边框可能会“吃掉”大量有效扇区面积导致图形扭曲。因此我个人的经验法则是将borderWidth设置为饼图半径以像素计的 1% 到 2%。例如如果你的饼图容器宽高为 400px半径radius设为‘45%’即约180px那么borderWidth设置在2到4之间会比较和谐。最好通过浏览器的开发者工具实时调整并预览。颜色设置的坑borderColor必须与图表直接父容器的背景色严格一致。如果你的图表放在一个背景为#f0f0f0的div里那么borderColor也必须设为#f0f0f0。否则间隔会显露出异色的边框破坏效果。在复杂的嵌套背景或渐变背景下此方法可能失效或效果不佳。2.3 环形图甜甜圈图的特殊处理对于环形图radius: [‘40%’ ‘70%’]这种形式这个方案依然有效但有一个额外的“坑”。环形图有内外两个边界。borderWidth会同时作用于内外边界。这意味着不仅扇区之间会产生间隔环形图内部的空心圆环边缘也会出现一圈“边框”。大多数情况下这圈内边缘的“边框”是无害的因为它也融入了背景。但如果你环形图的内半径区域有其他图形比如居中的文字这圈边框可能会轻微遮挡。如果你希望只在外圈边缘产生间隔内圈边缘保持光滑这个基础方案就无能为力了需要考虑方案二。3. 方案二操纵series.data的itemStyle实现高级间隔方案一虽然简单但它是“一刀切”的所有扇区的间隔都一样宽颜色也必须和背景一致。如果我们想要更灵活的控制比如不同扇区有不同的间隔宽度。间隔本身拥有独立的颜色比如统一的深色描边。在环形图上只让外圈有间隔。这时就需要深入到每个数据项data的维度进行配置。ECharts 允许我们为series.data数组中的每一个对象单独定义itemStyle。3.1 为每个扇区定制独立样式option { series: [{ type: pie, radius: 50%, data: [ { value: 335, name: 直接访问, itemStyle: { borderWidth: 4, borderColor: ‘#2c343c’ } // 深色间隔 }, { value: 310, name: 邮件营销, itemStyle: { borderWidth: 6, borderColor: ‘#2c343c’ } // 更宽的间隔 }, {value: 234, name: 联盟广告, itemStyle: { borderWidth: 4, borderColor: ‘#2c343c’ }}, {value: 135, name: 视频广告, itemStyle: { borderWidth: 4, borderColor: ‘#2c343c’ }}, {value: 1548, name: 搜索引擎, itemStyle: { borderWidth: 4, borderColor: ‘#2c343c’ }} ], // 全局的 itemStyle 仍然可以设置但会被 data 中单项的样式覆盖 itemStyle: { borderWidth: 2, borderColor: ‘#fff’ } }] };在这个配置中我们为“邮件营销”这个扇区设置了6px的边框而其他扇区是4px。这使得“邮件营销”与相邻扇区的间隔会显得更宽。同时我们将所有borderColor设置为一个统一的深色#2c343c这样间隔就不再是隐形的而是成了一道清晰的深色描边类似于设计软件中的“描边”效果能让饼图在浅色和复杂背景下都格外突出。3.2 实现“仅外圈有间隔”的环形图这个需求是方案一的短板却是方案二的强项。思路是只为环形图的外圈路径设置边框而不给内圈路径设置。但 ECharts 的borderWidth是同时作用于内外边的。怎么办我们需要一点“视觉把戏”用两个重叠的饼图系列来实现。底层系列一个完整的、无边框的环形图作为颜色填充的主体。顶层系列一个只有外圈有颜色、内圈透明并且设置了边框的饼图。这个饼图的每个扇区角度与底层完全一致但它的内半径要略小于底层系列的内半径使得它的内圈边缘被底层系列遮盖住。option { series: [ // 底层系列 - 主体 { type: pie, radius: [40%, 70%], label: { show: false }, // 标签通常在顶层显示 data: [...], // 你的数据 itemStyle: { borderWidth: 0 } // 无边框 }, // 顶层系列 - 仅用于绘制外圈间隔 { type: pie, radius: [40%, 70%], // 关键内半径增加一个很小的偏移量例如 1%让内圈边缘被底层覆盖 radius: [‘41%’, ‘70%’], data: [...], // 必须和底层系列数据顺序、值完全一致 itemStyle: { borderWidth: 3, borderColor: ‘#000’, // 间隔颜色 color: ‘transparent’ // 扇区本身透明只显示边框 }, label: { show: true, position: ‘outside’, // ... 你的标签配置 }, emphasis: { scale: false, scaleSize: 0 } // 禁用鼠标悬浮效果避免干扰 } ] };这个配置的精妙之处在于顶层系列因为扇区颜色是透明的所以本身不可见但它3px的黑色边框被渲染了出来。由于它的内半径41%比底层系列的内半径40%大它的内圈边框就绘制在了底层扇区的“身上”从而被遮盖掉了。最终只有外圈的边框即扇区间的间隔是可见的。注意这种方法需要确保两个系列的数据严格同步且顶层系列不应干扰交互如emphasis状态。它增加了图表的复杂度但能实现非常精细的视觉效果。4. 方案三使用series.pie.borderRadius的“曲线救国”方案在 ECharts 5.0 之后itemStyle新增了一个非常强大的属性borderRadius。它原本用于将矩形的柱状图变成圆角柱状图但在饼图上它有一个意想不到的妙用——通过将每个扇区设置为独立的圆角矩形视觉上来天然地产生间隔。4.1 borderRadius 属性详解borderRadius可以是一个数字也可以是一个数组[左上 右上 右下 左下]用于定义圆角大小。在饼图的上下文中ECharts 会智能地将这个圆角效果应用到每个扇区的两个径向边上。option { series: [{ type: pie, radius: 50%, data: [...], itemStyle: { borderRadius: 10, // 为每个扇区添加10像素的圆角 borderColor: ‘#fff’, borderWidth: 0 // 注意这里边框宽度为0 } }] };当你设置borderRadius: 10时你会发现扇区之间自动出现了空隙这是因为每个扇区靠近圆心的起始边缘和结束边缘都被“削”成了圆角。两个相邻扇区的圆角部分无法严丝合缝地拼接中间就留下了空隙。这个空隙的颜色是图表容器的背景色。4.2 方案对比与适用场景特性方案一 (统一边框)方案二 (独立边框)方案三 (圆角)实现原理用与背景同色的边框覆盖边缘为每个数据项单独定义边框样式利用扇区边缘的圆角产生空隙间隔颜色必须与背景色相同可任意指定为容器背景色间隔宽度控制通过borderWidth间接控制约为其2倍通过每个扇区的borderWidth直接控制通过borderRadius大小控制效果非线性环形图适配内外圈均会产生间隔可通过双层系列实现仅外圈间隔内外圈均会产生圆角间隔视觉效果干净、隐形的间隔灵活可实现描边等强调效果间隔边缘是弧形风格更柔和、现代复杂度简单一行配置中等需逐个配置或使用双层系列简单一行配置主要缺点背景色必须纯色且已知配置繁琐双层系列有性能开销间隔形状固定为弧形宽度控制不精确方案三的独特优势在于其风格的现代感。圆角间隔让饼图看起来不那么“锋利”更符合当前UI设计潮流。但它有一个小问题间隔的宽度并不直接等于borderRadius的值而且靠近圆心处的间隔会比外围的间隔更明显。它更适合追求特定视觉风格、且对间隔宽度要求不严苛的场景。5. 实战集成在 Vue/React 项目中的工程化实践知道了原理我们最终要将它应用到真实的项目中。这里以 Vue 3 TypeScript 项目为例展示如何封装一个高可用的、带间隔的饼图组件。5.1 封装可复用的 PieWithGap 组件我们选择方案一作为基础因为它最稳定、最简单。同时我们将通过props暴露关键参数使其可配置。!-- PieWithGap.vue -- template div refchartDom :style{ width, height }/div /template script setup langts import { ref, onMounted, onBeforeUnmount, watch } from vue; import * as echarts from echarts; import type { EChartsOption, PieSeriesOption } from echarts; interface Props { width?: string; height?: string; data: Array{ name: string; value: number }; // 间隔相关配置 gapWidth?: number; // 视觉期望的间隔宽度近似值 gapColor?: string; // 间隔颜色默认与背景同色 radius?: string | [string, string]; // 饼图半径 colors?: string[]; // 自定义调色板 } const props withDefaults(definePropsProps(), { width: ‘100%’, height: ‘400px’, gapWidth: 4, // 对应 borderWidth 约为 2 gapColor: ‘#fff’, radius: ‘75%’, colors: () [‘#5470c6’ ‘#91cc75’ ‘#fac858’ ‘#ee6666’ ‘#73c0de’ ‘#3ba272’ ‘#fc8452’ ‘#9a60b4’ ‘#ea7ccc’] }); const chartDom refHTMLElement(); let chartInstance: echarts.ECharts | null null; const initChart () { if (!chartDom.value) return; chartInstance echarts.init(chartDom.value); // 计算边框宽度gapWidth 是视觉间隔我们取一半作为 borderWidth const calculatedBorderWidth Math.max(1 Math.floor(props.gapWidth / 2)); const option: EChartsOption { color: props.colors, tooltip: { trigger: ‘item’ formatter: ‘{a} br/{b}: {c} ({d}%)’ }, legend: { orient: ‘vertical’ left: ‘left’ }, series: [ { name: ‘数据详情’ type: ‘pie’ radius: props.radius center: [‘50%’ ‘50%’] data: props.data emphasis: { itemStyle: { shadowBlur: 10 shadowOffsetX: 0 shadowColor: ‘rgba(0 0 0 0.5)’ } } label: { formatter: ‘{b|{b}}n{d|{d}%}’ rich: { b: { fontWeight: ‘bold’ fontSize: 14 } d: { color: ‘#999’ fontSize: 12 padding: [2 0] } } } labelLine: { length: 15 length2: 10 } // 核心间隔配置 itemStyle: { borderWidth: calculatedBorderWidth borderColor: props.gapColor // 可选添加轻微的阴影增强立体感让间隔更明显 shadowColor: ‘rgba(0 0 0 0.1)’ shadowBlur: 2 shadowOffsetX: 0.5 shadowOffsetY: 0.5 } } as PieSeriesOption ] }; chartInstance.setOption(option); }; // 响应窗口变化 const handleResize () { chartInstance?.resize(); }; onMounted(() { initChart(); window.addEventListener(‘resize’ handleResize); }); onBeforeUnmount(() { window.removeEventListener(‘resize’ handleResize); chartInstance?.dispose(); }); // 监听数据变化 watch(() props.data () { if (chartInstance) { chartInstance.setOption({ series: [{ data: props.data }] }); } } { deep: true }); // 监听间隔配置变化 watch(() [props.gapWidth props.gapColor] () { if (chartInstance) { const calculatedBorderWidth Math.max(1 Math.floor(props.gapWidth / 2)); chartInstance.setOption({ series: [{ itemStyle: { borderWidth: calculatedBorderWidth borderColor: props.gapColor } }] }); } }); /script这个组件封装了核心逻辑并通过gapWidth和gapColor两个props让父组件可以轻松控制间隔样式。注意我们将用户传入的gapWidth视觉间隔除以2作为borderWidth这是一个经验转换。5.2 动态背景下的自适应间隔颜色方案一最大的痛点在于borderColor必须与背景色一致。在主题切换或动态背景的页面中这很麻烦。解决方案是让组件能自动获取其父容器的背景色。我们可以利用getComputedStyleAPI 在组件挂载时获取chartDom元素的背景色并动态设置为borderColor。// 在 initChart 函数中获取背景色 const getParentBackgroundColor (): string { if (!chartDom.value || !chartDom.value.parentElement) return ‘#fff’; const bgColor window.getComputedStyle(chartDom.value.parentElement).backgroundColor; // 如果获取到的是透明或无效值可以返回一个默认值或继续向上查找 return bgColor bgColor ! ‘rgba(0 0 0 0)’ bgColor ! ‘transparent’ ? bgColor : ‘#fff’; }; const initChart () { // ... 其他代码 const autoGapColor props.gapColor ‘auto’ ? getParentBackgroundColor() : props.gapColor; // 在 option 中使用 autoGapColor // ... };同时你需要监听父容器背景色的变化如果会动态变化这可以通过MutationObserver监听父元素的style属性变化来实现但复杂度较高。更常见的做法是在应用切换主题时主动触发图表的重新渲染或更新gapColor属性。5.3 性能考量与大数据优化当饼图数据项非常多例如超过50个时每个扇区都会变得非常细长。此时再添加间隔可能会导致图形看起来像“刺猬”视觉效果很差。对于大数据量的饼图首要建议是考虑是否真的需要用饼图条形图可能是更好的选择。如果必须使用并且要加间隔有几点优化建议减小gapWidth/borderWidth数据项越多间隔应越细否则会过度挤占有效面积。使用方案三圆角对于大量细小的扇区小数值的borderRadius如1或2产生的弧形间隔可能比生硬的直线边框间隔看起来更柔和。关闭动画和阴影itemStyle中的shadowBlur等效果在数据项多时会带来较大的渲染开销可以考虑在数据量大时关闭。使用large模式ECharts 为饼图提供了large: true配置项用于优化大量数据的渲染性能。但在large模式下一些精细的样式如本方案依赖的边框可能渲染效果有差异需要实测。6. 避坑指南那些我踩过的“间隔”之坑在实际项目中实现这个效果远不止写对配置那么简单。下面分享几个我亲身踩过、并且花了时间才爬出来的坑。6.1 间隔在“南丁格尔玫瑰图”上的诡异表现南丁格尔玫瑰图本质上是半径与数据值相关的饼图。当你对玫瑰图应用边框间隔方案时会发现一个现象数据值越大的扇区其两侧的间隔看起来越宽数据值越小的扇区间隔越窄甚至消失。原因分析玫瑰图的扇区半径不同。borderWidth是一个固定的像素值它被“画”在扇区的路径边缘。对于半径很大的扇区固定的边框宽度在总半径中占比很小视觉上间隔明显。对于半径很小的扇区同样的边框宽度几乎“吞噬”了整个扇区的径向宽度导致扇区本身变得非常细间隔感反而弱了甚至因为图形太小边框渲染可能出现锯齿或重叠。解决方案放弃固定像素改用百分比borderWidth不支持百分比值此路不通。方案三的变体尝试对玫瑰图使用borderRadius。由于玫瑰图扇区是弯曲的圆角会产生一种独特的效果可能比边框方案更合适但需要大量调试。接受并说明对于玫瑰图或许“均匀间隔”本身就不是一个合理的需求。更好的做法是不加间隔而是通过label和color的强烈对比来区分扇区。6.2 高亮emphasis状态下的样式冲突ECharts 的饼图在鼠标悬浮时默认会有扇区“放大突出”的效果emphasis: { scale: true scaleSize: 10 }。当你为扇区设置了边框后这个“放大”效果可能会带来问题放大的扇区会覆盖相邻扇区的边框导致间隔在悬浮时“消失”或变形。解决方法精细控制emphasis状态下的样式。你需要明确指定悬浮时边框的行为。itemStyle: { borderWidth: 4 borderColor: ‘#fff’ } emphasis: { itemStyle: { borderWidth: 6 // 悬浮时边框可以加粗让间隔更明显 borderColor: ‘#fff’ shadowBlur: 15 // 增强悬浮效果 shadowColor: ‘rgba(0 0 0 0.3)’ } }确保emphasis.itemStyle.borderColor与正常状态一致否则悬浮时颜色突变会很突兀。如果希望悬浮时扇区“飞”出来间隔依然保持可以将emphasis.scaleSize设得更大并确保borderWidth也随之等比增加。6.3 导出静态图片时的清晰度问题当你使用 ECharts 提供的getDataURL()方法将带有间隔的饼图导出为 PNG 或 JPEG 图片时在低分辨率或高压缩比的设置下白色的细间隔尤其是borderWidth为1或2时可能会因为抗锯齿或压缩算法而变得模糊、断续甚至消失。解决方案适当增加borderWidth用于导出的图表可以临时将borderWidth调大1-2像素确保间隔在像素级别足够明显。使用type: ‘svg’导出SVG 是矢量格式不受分辨率影响。调用chartInstance.getDataURL({ type: ‘svg’ pixelRatio: 2 })可以获得在任何缩放级别下都清晰的图片。pixelRatio: 2可以导出更高精度的栅格化版本如果后端需要栅格图。避免使用极细的间隔在设计阶段就考虑到导出需求间隔宽度不要小于3px视觉宽度约6px。6.4 与“富文本标签”rich的定位协调如果你使用了 ECharts 的富文本标签label.rich在扇区内部或外部进行复杂的标注增加的间隔可能会影响你的定位计算。例如你原本根据扇区中心角计算的标签位置可能会因为扇区实际绘制区域扣除了边框区域的缩小而产生偏移。调试建议在添加间隔效果后务必仔细检查所有标签的位置。你可能需要微调label.position如‘inside’‘outside’、label.distance或label.rotate等参数。一个实用的技巧是先完成间隔的配置再从头调整标签的样式和位置而不是反过来。实现 ECharts 饼图的间隔效果就像是在已有的精密仪器上做一次微创手术。它不改变仪器饼图的核心功能却通过精巧的“视觉戏法”显著提升了其表现力。从最朴素的同色边框法到高度定制化的独立样式法再到利用新特性的圆角法每种方案都有其独特的适用场景和代价。选择哪一种取决于你的设计需求、技术环境和性能预算。记住可视化永远是为清晰传达信息服务的间隔只是一种手段而非目的。当你的饼图扇区多到必须依靠间隔才能区分时或许应该首先反思饼图是否是展示这批数据的最佳选择。