1. 为什么饼图配置总让人抓狂做前端数据可视化这些年ECharts 的饼图是我见过“上手最快、配好最难”的图表类型。默认渲染出来的那个饼能跑但基本没法直接放进生产环境——要么尺寸跟容器打架要么图例挤成一坨要么引导线末端的文字飘到画布外面被裁掉。尤其是最近做 Vue3 项目热词里提到的pxtorem对 ECharts 不生效这个坑我在两个项目里连续踩过。先把结论摆在前面饼图配置的核心矛盾就三组——容器尺寸与图表尺寸的博弈、图例位置与画布留白的博弈、标签引导线与数据密度的博弈。这三组矛盾处理好了饼图基本就服帖了。这篇文章适合谁看如果你是刚接手一个看板项目、被设计稿上那个精致的甜甜圈图卡住的前端或者你已经用过 ECharts 但每次都要翻官方文档的配置项那这篇可以直接当备忘录用。我下面给的配置都是能在项目里直接跑的参数取舍的理由我也会讲清楚不是把文档抄一遍。提前说一句ECharts 版本建议 5.x 以上。4.x 到 5.x 在默认主题和部分属性上有变化比如labelLine的默认长度和emphasis的缩放行为我会在对应位置标注。2. 项目整体设计与配置思路拆解2.1 用一个配置对象管住所有饼图我现在的习惯是不在setOption里散写对象而是抽一个工厂函数把饼图的变体实心饼、环形图、玫瑰图都用参数控制。原因很实在一个中后台项目里往往有十几处饼图每处都手写一遍series.type: pie的配置改一次全局样式要改十几处维护成本爆炸。工厂函数的结构长这样// pieFactory.js export function createPieOption({ data [], radius [0%, 70%], center [50%, 50%], legendPosition right, labelFormatter {b}: {d}%, } {}) { return { tooltip: { trigger: item, formatter: {b}: {c} ({d}%) }, legend: buildLegend(legendPosition), series: [buildSeries({ data, radius, center, labelFormatter, legendPosition })], }; }这里第一个设计决策是radius用数组而不是单值。数组形式[内径, 外径]才能画环形图单值只能画实心饼。统一用数组视觉切换时只改内径外径不动图表占地面积不变布局不会跳。第二个决策是center一定显式写。ECharts 默认居中但当图例放在右侧时图表实际可用区域会被图例吃掉一块如果center还是[50%, 50%]饼会压在图例下面。显式设置中心点是让布局可控的前提。经典做法是图例在右侧时把center的横坐标往左推比如[40%, 50%]留出右侧空间。第三个决策是图例位置做成枚举而不是让调用方传对象。legendPosition只接受right | bottom | top | left四个值由工厂函数内部映射成完整的legend配置。这样调用方不会写出位置正确但没给empadding/em的半成品配置。2.2 尺寸方案为什么我最终选了 rem 换算而不是缩放热词里pxtorem 对 echarts 没起到效果 vue3这个问题的根因值得单独说清楚。postcss-pxtorem是在编译时扫描 CSS/SCSS/Less 文件里的 px 值把样式表中的px替换成rem。而 ECharts 的尺寸如果你是通过 JS 配置里的radius: 80这种数值传的它压根不经过 PostCSS 的 AST自然不会被转换。所以正确姿势有两条路路径 AJS 里也用 rem。ECharts 支持radius: 5rem这种字符串形式吗答案是部分支持radius、center、itemWidth这类相对尺寸接受百分比字符串但 rem 字符串在很多版本里会被忽略并回退默认值。稳妥起见别赌。路径 B推荐用 JS 读取根节点字号动态算出 px。function getRemPx(rem) { const rootFontSize parseFloat( getComputedStyle(document.documentElement).fontSize ); return rem * rootFontSize; } // 使用 const chartSize { radius: [getRemPx(2), getRemPx(5)], // 内径2rem外径5rem };这样一来屏幕宽度变化 → 根字号变化 → 饼图半径跟着变跟 CSS 里的 rem 布局保持同一套缩放基准。窗口 resize 时记得重新计算并setOption下面第 5 章会给出完整的 resize 处理。路径 B 相比“给整个图表容器做 CSS transform scale”的优势在哪transform 缩放会把文字、引导线一起放大导致字号不再是设计稿的整数倍糊边、发虚而 rem 换算只影响几何尺寸字号仍是固定 px清晰度不受影响。我在一个大屏项目里两种方案都试过最终全量换成了路径 B。2.3 图例位置与画布留白的分配策略图例位置不是随便挑的它决定了画布空间的分配模型。我把四种位置的适用场景和留白策略整理成一张表图例位置配置写法画布留白策略适用场景右侧orient: vertical, right: 10center横坐标左移到 40%~45%图例项少于 6 项容器偏宽底部orient: horizontal, bottom: 10center纵坐标上移到 42%或缩外径图例项多、容器偏扁顶部orient: horizontal, top: 10center纵坐标下移到 55%图例项少标题区已占用左侧orient: vertical, left: 10center横坐标右移到 55%~60%主视觉偏右的突破性布局为什么“右侧”时center只推到 40% 而不是 45%~50%因为饼图的半径是以center为圆心向外辐射的如果你把中心推到 45%外径 70% 时饼的右边缘就在45% 70% 115%……等等这里有个常见误解需要澄清radius的百分比是相对容器短边计算的而center是相对容器宽高的百分比。所以当容器是宽高比 2:1 的长条时radius: 70%的实际像素半径是0.7 × 高度 / 2占宽度的比例远小于 70%。理解这一点你才能准确预估饼的右边缘落点。我一般的算法是先量出饼的实际像素半径R radiusPercent × min(width, height) / 2再保证centerX_px - R legendWidth padding。图例宽度可以在渲染后通过getModel()拿但更实用的做法是估每个图例项约 80~120px最多显示 8 项纵向图例宽度按 120px 预留。提示图例项数超过容器能容纳的行数时ECharts 默认会分页legend.type: scroll需要手动开启否则会静默丢弃超出部分。如果你发现图例少了项先检查是不是被截断了。3. 核心配置项逐一拆解与实操要点3.1 饼图大小radius、center 与容器尺寸的三角关系先说最容易搞错的一点radius的百分比基准是容器的短边不是宽或高。假设容器 800×400radius: 100%→ 实际直径 400px短边 400饼高已经顶格左右两边各留 200px 空白。想让饼占满宽度的 60%实际需要的radius百分比是800 × 0.6 / 400 120%但 120% 会超出高度吗直径 480 400上下会溢出。所以长条形容器里饼图的“大小”永远受短边压制这就是为什么宽屏看板里的饼经常显得孤零零的。解决办法有两个要么给饼图一个接近正方形的容器用 grid 布局的aspect-ratio: 1/1要么在长条容器里放一行多个饼图。内径与外径的比例我推荐图形类型内径/外径观感标准环形图0.5 ~ 0.6环宽度适中中心可放总数细环形图0.7 ~ 0.8轻盈适合仪表盘实心饼0 或 0%传统占比图玫瑰图用roseType: radius单值对比非占比中心放总数文字的做法是加一个title并调位置或者用graphic。我倾向graphic因为 title 会在图例布局变化时被顶走graphic: [ { type: text, left: center, top: center, style: { text: 总计\n1,286, textAlign: center, fontSize: 16, lineHeight: 22, fill: #333, }, }, ],注意left: center是相对整个画布居中如果中心被center配置挪走了这个文字就会偏。这时候要么同步调整graphic.left要么改用相对坐标百分比跟center保持同一个值。3.2 图例位置样式的完整配置图例配置我拆成四块位置、排布方向、样式、交互。位置用left/right/top/bottom四件套配合orient决定方向。右侧竖排的典型写法legend: { orient: vertical, right: 20, top: center, itemWidth: 10, itemHeight: 10, itemGap: 12, icon: circle, textStyle: { color: #666, fontSize: 12, padding: [0, 0, 0, 6], }, formatter: (name) { const item data.find((d) d.name name); const pct ((item.value / total) * 100).toFixed(1); return ${name} ${pct}%; }, }几个细节值得单独拎出来讲。itemWidth和itemHeight默认是 25 和 14对 12px 的字号来说明显偏大视觉上图例图标像个小方块。改成跟字号接近的 10×10配icon: circle整个图例会精致很多。itemGap默认 10行距偏挤调到 12~14 更透气。formatter是图例最值得动的地方。默认只显示名称但用户看饼图最想知道的是“每项占多少”。把百分比拼进图例等于把label的信息前移即使读者不看饼上的引导线也能 get 到占比。代码里的total需要提前用reduce算好const total data.reduce((sum, d) sum d.value, 0);formatter拿不到 index只能拿到 name所以要靠 name 回查数据。这里有个性能提醒formatter在每次重绘时会对每个图例项调用一次数据项上千时会明显卡记得对数据做find前的 Map 预建索引。底部横排的写法差异在于orient: horizontal并去掉right改bottomlegend: { orient: horizontal, bottom: 10, left: center, itemGap: 16, // 其余同上 }底部图例最大的问题是项数多时换行换行后图例高度增加会跟饼重叠。legend没有自动“把饼顶上去”的能力得手动调center的纵坐标或缩radius。我的经验值是底部图例每多一行center[1]上移 3%~5%。3.3 指示文字label与引导线labelLine样式这块是热词里echarts 饼图 labelline 末尾小圆点偏移的直接对应。先说清楚引导线的结构一条labelLine由length第一段从扇区边缘出发和length2第二段折向文字的水平段组成末端那个小圆点其实是labelLine的样式特征通过symbol和symbolSize控制。labelLine: { show: true, length: 15, length2: 20, smooth: false, // true 时为曲线引导线 lineStyle: { color: #999, width: 1, type: solid, }, // 末端小圆点 symbol: circle, symbolSize: 4, symbolOffset: [0, 0], }小圆点“偏移”的常见原因是symbolOffset没设或者设成了非零值以及length2太短导致圆点压在文字上。实测length2至少给 15圆点才不会跟文字黏在一起。如果你的版本里labelLine.symbol不生效部分 5.0 早期版本对饼图引导线的 symbol 支持不完备退路是在label.formatter里用富文本画个点但那样点会跟着文字走位置精度不如原生的符号。label本身的配置label: { show: true, position: outside, formatter: {b}\n{d}%, color: #333, fontSize: 12, lineHeight: 18, align: center, verticalAlign: middle, // 防止文字超出画布 overflow: break, ellipsis: ..., }position有三个值outside外部带引导线、inside扇区内、center饼中心只对单扇区有意义。数据项少的时候outside好看数据项超过 8 个且容器不大时引导线会交叉打架这时候果断换inside并把字号缩到 10~11label: { position: inside, formatter: {d}%, color: #fff, fontSize: 10, }inside模式下数据项按值排序很有必要小扇区挤在一起会看不清把值接近的扇区排到一起阅读连续性更好。关于overflow和ellipsis小容差情形下文字被裁是高频问题。overflow: break会强制换行配合width限制label: { width: 60, overflow: break, ellipsis: ..., }设了width后超长名称会换成两行再超就加省略号。实测width给 50~70 覆盖绝大多数中文名称。3.4 颜色与高亮调色盘与 emphasis默认调色盘是那套经典蓝绿黄橙红饱和度偏高。业务看板里我一般换一套低饱和的color: [#5B8FF9, #61DDAA, #65789B, #F6BD16, #7262FD, #78D3F8],这六个颜色亮度接近相邻色相的对比度足够区分又不会刺眼。数量上建议备 8 个以上饼图超过 8 项时如果颜色循环会让人误读为“同一类”可以在formatter里提示“其他”合并或者对第 9 项起用同色系深浅区分。高亮的配置写法要注意ECharts 5 用的是emphasis而不是老的highlightemphasis: { scale: true, scaleSize: 6, itemStyle: { shadowBlur: 12, shadowColor: rgba(0, 0, 0, 0.2), borderWidth: 2, borderColor: #fff, }, label: { show: true, fontWeight: bold, }, }scale: true时鼠标悬停扇区会向外扩视觉反馈很好但要注意scaleSize别给太大否则相邻扇区会被盖住。6px 是个比较克制的值。borderWidth borderColor白边在扇区放大时能隔开彼此观感更清爽。还有一处容易漏关闭或调整labelLine在 hover 时的显示。默认emphasis.labelLine会跟随emphasis.label显示如果label平时是inside隐藏的hover 时突然冒出引导线会很突兀。稳妥做法是把emphasis.labelLine.show显式设为false。4. 完整实操流程与关键环节实现4.1 从零搭一个可复用的饼图组件Vue3 版我直接给一个能复制的完整实现包含尺寸自适应、rem 换算、图例和三态标签。第一步模板部分template div refchartRef classpie-chart/div /template style scoped .pie-chart { width: 100%; height: 100%; min-height: 260px; } /style第二步组合式逻辑。核心是ResizeObserver用它比监听window.resize更准因为很多看板是面板折叠导致容器变化窗口尺寸没变import { ref, onMounted, onBeforeUnmount, watch } from vue; import * as echarts from echarts; export default { props: { data: { type: Array, default: () [] }, isDonut: { type: Boolean, default: true }, }, setup(props) { const chartRef ref(null); let chart null; let ro null; const getRemPx (rem) { const fs parseFloat(getComputedStyle(document.documentElement).fontSize); return rem * fs; }; const buildOption () { const data props.data; const total data.reduce((s, d) s d.value, 0); const inner props.isDonut ? 50% : 0%; return { color: [#5B8FF9, #61DDAA, #65789B, #F6BD16, #7262FD, #78D3F8], tooltip: { trigger: item, formatter: {b}: {c} ({d}%), confine: true, }, legend: { orient: vertical, right: 12, top: center, icon: circle, itemWidth: 10, itemHeight: 10, itemGap: 12, textStyle: { color: #666, fontSize: 12 }, formatter: (name) { const item data.find((d) d.name name); if (!item) return name; const pct ((item.value / total) * 100).toFixed(1); return ${name} ${pct}%; }, }, series: [ { name: 占比, type: pie, radius: [inner, 62%], center: [38%, 50%], avoidLabelOverlap: true, itemStyle: { borderColor: #fff, borderWidth: 2, borderRadius: 4, }, label: { show: true, position: outside, formatter: {b}\n{d}%, color: #333, fontSize: 12, lineHeight: 18, }, labelLine: { show: true, length: 12, length2: 16, lineStyle: { color: #ccc, width: 1 }, symbol: circle, symbolSize: 4, }, emphasis: { scale: true, scaleSize: 6, itemStyle: { shadowBlur: 12, shadowColor: rgba(0,0,0,0.2), }, label: { show: true, fontWeight: bold }, labelLine: { show: true }, }, data, }, ], }; }; const render () { if (!chart) return; chart.setOption(buildOption(), true); }; onMounted(() { chart echarts.init(chartRef.value); render(); ro new ResizeObserver(() { chart chart.resize(); // rem 基准变化时radius 若是 px 数值需重算见 4.2 说明 }); ro.observe(chartRef.value); }); watch(() props.data, render, { deep: true }); onBeforeUnmount(() { ro ro.disconnect(); chart chart.dispose(); chart null; }); return { chartRef }; }, }; /script这段代码里几个决策的意图tooltip.confine: true是必加项。默认 tooltip 会跟随鼠标并可能超出容器边界被父级overflow: hidden裁掉。confine让它限制在图表容器内。小屏看板上这一条能省掉很多“提示框看不全”的反馈。series.avoidLabelOverlap: true处理外部标签重叠。算法会把邻近标签上下推开但推开后引导线会拉长。如果发现引导线长得难看可以配合labelLayout5.x 新特性labelLayout: { hideOverlap: true, },hideOverlap更激进直接隐藏重叠的标签适合数据项多且不追求全部标签可见的场景。两者选哪个优先avoidLabelOverlap被推开后仍显拥挤再上hideOverlap。borderRadius: 4给扇区加圆角这是 5.x 才有的细节视觉精致感提升明显但仅在扇区数量不多小于 10时不显散。数据项很多时建议去掉改成borderWidth: 1。4.2 rem 场景下的尺寸重算接着上面的组件如果radius你写的是 px 数值而不是百分比ResizeObserver里只调resize()是不够的因为根字号变了但数值没变。这时候要在 resize 回调里重算ro new ResizeObserver(() { const option buildOption(); chart chart.setOption(option, true); });把buildOption()里的radius改成基于getRemPx的计算值const rOuter getRemPx(5); const rInner props.isDonut ? getRemPx(2.5) : 0; // radius: [rInner, rOuter]注意每次 resize 都全量setOption有性能代价最好加个节流。实测 100ms 节流对拖动面板的场景已经足够顺滑。还有一种情况如果你用了热词里提到的pxtorem而饼图尺寸是在 SCSS 里写死的比如给容器写了width: 300pxPostCSS 会把容器的 300px 转成 rem但 ECharts 里的数值没转于是布局对不上。诊断方法打开 DevTools 看容器的 computed width 是不是 rem 换算后的值再对比饼图实际渲染尺寸。对不上就用 4.2 的方案统一到 rem 基准。4.3 玫瑰图与南丁格尔变体的快速切换同一份数据换一种表达只要改一个属性series: { type: pie, roseType: radius, // 或 area radius: [20%, 70%], // 其余配置通用 }roseType: radius时每个扇区的半径随数值变化但角度相同area时面积随数值变化。前者的对比更夸张后者更接近真实比例的感知。玫瑰图不表达占比所以标签里不要再写{d}%改成显示数值label: { formatter: {b}\n{c} }玫瑰图的扇区大小差异大引导线更容易交叉务必开avoidLabelOverlap并考虑把labelLine.length缩短到 8~10减少视觉噪音。5. 常见问题排查与避坑实录5.1 高频问题速查表现象根因解决饼图不显示或空白容器无宽高echarts.init时拿到 0 尺寸给容器显式height或init前nextTick图例少了项超出容器未开启滚动legend.type: scroll引导线末端文字被裁文字超出画布边缘调小radius或center内移开overflow: break小圆点位置偏移length2太短或symbolOffset非零length2 ≥ 15symbolOffset: [0,0]hover 时饼图跳变center或radius用了百分比emphasis.scale触发重排缩小scaleSize或关闭scalepxtorem 后尺寸错位JS 里的 px 未参与转换JS 侧用getRemPx动态算tooltip 超出容器被裁默认不约束tooltip.confine: true扇区颜色循环重复数据项超过color数组长度扩充色板或合并“其他”环形中心文字偏移graphic.left与series.center基准不一致两者取同一百分比resize 后图表没变容器尺寸变了但未调用resize()用ResizeObserver监听容器这张表里的每一条我都在项目里实打实遇到过。挑两个展开。5.2 “容器无宽高导致空白”的真实排查过程这个问题第一次遇到时我盯了半天配置以为series写错了。实际原因很朴素我把图表容器放在一个display: flex的父级里容器自己没设高度父级也没撑开offsetHeight是 0。ECharts 在init时读取容器尺寸0 宽或者 0 高会导致 canvas 尺寸为 0什么都不画。排查顺序我固定成三步在init前打印chartRef.value.clientWidth和clientHeight是不是 0。如果是 0往上找父级看哪一层没撑开。常见的是height: 100%链条断了或者 flex 子项没给flex: 1。在 Vue 里如果是路由切换后立即initDOM 可能还没渲染完用await nextTick()包一层。修复方式我一般选给容器一个min-height比如 260px保证最差情况也有尺寸。这也解释了为什么我在组件样式里写了min-height: 260px——它不是审美选择是防御性编程。5.3 tooltip 自动换行与长文本处理热词里的echarts tooltip自动换行也是高频需求。项目名很长的时候tooltip 会拉成一整行很难看。ECharts 的 tooltip 默认不换行需要在 formatter 里手动加\n或者用extraCssText限制宽度tooltip: { trigger: item, formatter: (params) { const name params.name; // 简单按长度切分中文场景够用 const wrapped name.length 12 ? name.replace(/(.{12})/g, $1\n) : name; return ${wrapped}br/数值${params.value}${params.percent}%; }, extraCssText: max-width: 240px; white-space: normal; word-break: break-all;, }extraCssText里的white-space: normal是关键的ECharts 默认 tooltip 是nowrap光加max-width不会换行。word-break: break-all保证无空格的长串比如英文项目编码也能断。如果要更精细可以把 formatter 返回 DOM 节点或者用appendToBody避免被父级overflow裁切。appendToBody: true在弹窗内的图表里特别有用因为我遇到过弹窗的overflow: auto把 tooltip 裁掉一半的情况。5.4 一些不太上文档的经验关于扇区排序默认按数据顺序绘制视觉上杂乱。我习惯在传给 ECharts 前先按值降序排一遍。排序后扇区从大到小顺时针排列阅读节奏顺很多。但注意图例的排序是独立于扇区的图例默认按name排想让它跟扇区顺序一致得显式给图例也排一遍或者关掉图例的自动排序习惯自己控制数组顺序。关于空数据数据为空数组时 ECharts 渲染一个空画布用户体验很差。加一层状态判断显示“暂无数据”的占位比让用户看空白强。实现上可以画一个灰色圆环加文字或者直接在容器上叠一个v-if的占位 div。关于数值格式化{d}的精度是固定一位小数但业务上常要“大于万显示万”。这种情况别硬改{d}用formatter函数自己算label: { formatter: (p) { const v p.value; const text v 10000 ? (v / 10000).toFixed(1) 万 : v; return ${p.name}\n${text}; }, }关于多饼图联动一行放多个饼时legend容易重复我一般只在第一个饼显示图例其余饼通过legend: { show: false }关掉用 tooltip 各自独立提示。关于动画默认的入场动画是从中心“长”出来数据变化时会重新动画。频繁更新的场景比如实时看板建议设animationDurationUpdate: 300比默认的 1000 干练很多不会让页面显得一直在转。关于导出图片getDataURL()出来的图默认无背景透明如果要用在 PPT 里记得传{ backgroundColor: #fff }否则贴上去在深色背景看会很难读。关于移动端小屏上引导线几乎必然打架我的做法是断点判断宽度小于 480px 时强制label.position: inside并只显示百分比名称交给图例承担。关于labelLine.smooth曲线引导线在数据项少的时候挺优雅但smooth: true会让引导线的折点消失末端小圆点的位置判定变得不直观调样式时容易迷失。调试阶段先设false样式定死了再考虑打开。6. 性能、兼容与后续扩展的实操体会饼图本身的计算量很小性能瓶颈基本都在标签布局上。数据项超过 30 个的饼图无论怎么调视觉上都很难读这时候正确做法不是在 ECharts 配置上死磕而是回到数据层做 TOP N “其他”合并。我做过一个 60 项的设备占比饼最终合并到 TOP 8 其他图一下子清爽了业务方也更满意——他们本来也不关心第 30 名的品类。5.x 相比 4.x 在标签布局上有明显改进尤其是labelLayout的引入让过密标签的处理从“手工算坐标 graphic 硬画”升级成配置项。如果你还在 4.x外部标签重叠的问题基本只能靠avoidLabelOverlap和调半径缓解能升就升。关于ResizeObserver的兼容性现代浏览器都支持但如果要覆盖较老的环境需要 polyfill 或者退回window.resize 定时轮询容器尺寸。我现在的项目基本不再考虑这个退路直接在构建配置里声明目标浏览器。后续扩展可以从两个方向走。一个是下钻交互点击某个扇区把该扇区的明细数据换进来重绘实现“总览 → 明细”的钻取。实现上是监听chart.on(click, params {...})把 params 里的 name 作为过滤条件重新请求或过滤本地数据再setOption。注意切换时要保留一块返回按钮否则用户进得去出不来。另一个方向是与其他图表的联动高亮用echarts.connect把饼图和一个柱状图绑在一起hover 饼时对应柱条也高亮。这个功能在对比“占比”和“绝对值”时特别好用但要注意两个图的series.name和data.name要严格一致否则连不上。我把这套饼图配置沉淀成了一个内部 npm 包团队里谁要做饼图直接install引用参数只暴露数据、尺寸模式和图例位置。沉淀的过程本身就是一次配置项的去芜存菁——你会发现真正需要外部控制的参数不超过 8 个其余都可以在内部定死。这也是我这几年的一个整体感受图表配置的价值不在“可配置项多”而在“默认值合理到不改也能用”。