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' // 关键：边框颜色，通常设置为背景色 } }] };

原理分析：

1. 视觉欺骗：当我们将borderColor设置为与图表容器背景色（例如白色#fff）一致时，这个边框在视觉上就“消失”了，因为它融入了背景。
2. 空间挤占：borderWidth定义的边框是从扇区路径的内外两侧同时延伸的。一个5px的边框，会在扇区边缘的内外各占据2.5px（具体算法可能因渲染引擎略有差异，但概念如此）。正是这向“内部”延伸的部分，覆盖了原本扇区与扇区紧邻的边缘区域。
3. 间隔形成：两个相邻的扇区，各自都有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是同时作用于内外边的。怎么办？我们需要一点“视觉把戏”：用两个重叠的饼图系列来实现。

1. 底层系列：一个完整的、无边框的环形图，作为颜色填充的主体。
2. 顶层系列：一个只有外圈有颜色、内圈透明，并且设置了边框的饼图。这个饼图的每个扇区角度与底层完全一致，但它的内半径要略小于底层系列的内半径，使得它的内圈边缘被底层系列遮盖住。

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 方案对比与适用场景

方案三的独特优势在于其风格的现代感。圆角间隔让饼图看起来不那么“锋利”，更符合当前UI设计潮流。但它有一个小问题：间隔的宽度并不直接等于borderRadius的值，而且靠近圆心处的间隔会比外围的间隔更明显。它更适合追求特定视觉风格、且对间隔宽度要求不严苛的场景。

5. 实战集成：在 Vue/React 项目中的工程化实践

知道了原理，我们最终要将它应用到真实的项目中。这里以 Vue 3 + TypeScript 项目为例，展示如何封装一个高可用的、带间隔的饼图组件。

5.1 封装可复用的 PieWithGap 组件

我们选择方案一作为基础，因为它最稳定、最简单。同时，我们将通过props暴露关键参数，使其可配置。

<!-- PieWithGap.vue --> <template> <div ref="chartDom" :style="{ width, height }"></div> </template> <script setup lang="ts"> 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(defineProps<Props>(), { width: ‘100%’, height: ‘400px’, gapWidth: 4, // 对应 borderWidth 约为 2 gapColor: ‘#fff’, radius: ‘75%’, colors: () => [‘#5470c6’， ‘#91cc75’， ‘#fac858’， ‘#ee6666’， ‘#73c0de’， ‘#3ba272’， ‘#fc8452’， ‘#9a60b4’， ‘#ea7ccc’] }); const chartDom = ref<HTMLElement>(); 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个）时，每个扇区都会变得非常细长。此时再添加间隔，可能会导致图形看起来像“刺猬”，视觉效果很差。对于大数据量的饼图，首要建议是考虑是否真的需要用饼图，条形图可能是更好的选择。

如果必须使用，并且要加间隔，有几点优化建议：

1. 减小gapWidth/borderWidth：数据项越多，间隔应越细，否则会过度挤占有效面积。
2. 使用方案三（圆角）：对于大量细小的扇区，小数值的borderRadius（如1或2）产生的弧形间隔可能比生硬的直线边框间隔看起来更柔和。
3. 关闭动画和阴影：itemStyle中的shadowBlur等效果在数据项多时会带来较大的渲染开销，可以考虑在数据量大时关闭。
4. 使用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时）可能会因为抗锯齿或压缩算法而变得模糊、断续甚至消失。

解决方案：

1. 适当增加borderWidth：用于导出的图表，可以临时将borderWidth调大1-2像素，确保间隔在像素级别足够明显。
2. 使用type: ‘svg’导出：SVG 是矢量格式，不受分辨率影响。调用chartInstance.getDataURL({ type: ‘svg’， pixelRatio: 2 })可以获得在任何缩放级别下都清晰的图片。pixelRatio: 2可以导出更高精度的栅格化版本（如果后端需要栅格图）。
3. 避免使用极细的间隔：在设计阶段就考虑到导出需求，间隔宽度不要小于3px（视觉宽度约6px）。

6.4 与“富文本标签”（rich）的定位协调

如果你使用了 ECharts 的富文本标签（label.rich）在扇区内部或外部进行复杂的标注，增加的间隔可能会影响你的定位计算。例如，你原本根据扇区中心角计算的标签位置，可能会因为扇区实际绘制区域（扣除了边框区域）的缩小而产生偏移。

调试建议：在添加间隔效果后，务必仔细检查所有标签的位置。你可能需要微调label.position（如‘inside’，‘outside’）、label.distance或label.rotate等参数。一个实用的技巧是，先完成间隔的配置，再从头调整标签的样式和位置，而不是反过来。

实现 ECharts 饼图的间隔效果，就像是在已有的精密仪器上做一次微创手术。它不改变仪器（饼图）的核心功能，却通过精巧的“视觉戏法”显著提升了其表现力。从最朴素的同色边框法，到高度定制化的独立样式法，再到利用新特性的圆角法，每种方案都有其独特的适用场景和代价。选择哪一种，取决于你的设计需求、技术环境和性能预算。记住，可视化永远是为清晰传达信息服务的，间隔只是一种手段，而非目的。当你的饼图扇区多到必须依靠间隔才能区分时，或许应该首先反思，饼图是否是展示这批数据的最佳选择。