Python pyecharts生成交互式饼状图代码
使用 Python pyecharts 库生成交互式饼状图的完整教程与代码示例,涵盖基础饼图、环形图、南丁格尔玫瑰图的配置方法及常见排错指南。
在 Python 数据可视化中,想要生成支持鼠标悬停浮动提示、图例联动切换、动态扇区高亮及缩放过滤的交互式饼状图,基于 Apache ECharts 封装的开源库 pyecharts 是高效实用的选择。与 Matplotlib 或 Seaborn 生成静态位图不同,pyecharts 通过 Python 构建配置并直接渲染出包含原生 JavaScript 交互逻辑的独立 HTML 文件。本文提供从环境依赖安装、最简可运行示例,到环形图、南丁格尔玫瑰图定制及高频问题排查的完整指南。
一、环境准备与依赖安装
在编写代码前,需要确保系统中已安装 Python 3.8 及以上环境。pyecharts 目前的主流稳定版本为 v2.x,请通过终端中的 pip 工具执行安装命令:
pip install pyecharts
安装完成后,可在命令行通过 python -c "import pyecharts; print(pyecharts.__version__)" 验证安装是否成功。注意:pyecharts v0.5.x 与 v2.x 之间存在重大的语法不兼容,目前所有生产代码均应使用基于 opts 选项类的现代化链式调用语法。
二、基础交互式饼图实现与代码解析
pyecharts 的饼图组件使用 Pie 类构建。在底层逻辑上,数据必须以“二元序列”(即每个元素为 (名称, 数值) 或 [名称, 数值] 的列表)形式传入。构建流程包括数据准备、类目实例化、配置项装配和渲染四个环节。
以下是生成标准交互式饼状图的完整可执行代码:
from pyecharts import options as opts
from pyecharts.charts import Pie
# 1. 准备分类与对应数值数据
categories = ["直接访问", "邮件营销", "联盟广告", "视频广告", "搜索引擎"]
values = [335, 310, 234, 135, 1548]
# 组装为 pyecharts 要求的键值对列表: [list(z) for z in zip(categories, values)]
data_pair = [list(item) for item in zip(categories, values)]
# 2. 链式构建饼图
pie = (
Pie()
.add(
series_name="访问来源",
data_pair=data_pair,
radius=["0%", "75%"], # 内径 0%,外径 75%,即实心饼图
center=["50%", "50%"], # 饼图圆心在画布中的坐标位置
)
.set_global_opts(
title_opts=opts.TitleOpts(
title="网站流量来源占比",
subtitle="年度统计明细数据",
pos_left="center"
),
legend_opts=opts.LegendOpts(
orient="vertical", # 图例垂直排列
pos_left="left", # 图例靠左显示
pos_top="middle" # 图例垂直居中
),
tooltip_opts=opts.TooltipOpts(
trigger="item",
formatter="{a} <br/>{b}: {c} ({d}%)" # 悬停提示格式
)
)
.set_series_opts(
label_opts=opts.LabelOpts(
formatter="{b}: {d}%" # 饼图外侧标签格式
)
)
)
# 3. 输出并保存为本地 HTML 网页
pie.render("basic_pie_chart.html")
print("交互式饼图已生成: basic_pie_chart.html")
三、常见衍生形态:环形图与南丁格尔玫瑰图
在实际业务中,单一的实心饼图容易在大面积显示时产生视觉疲劳。通过调整 radius 参数或启用 rosette_type,可以轻松衍生出空心环形图与南丁格尔玫瑰图。
1. 空心环形图 (Donut Chart)
环形图通过保留内部圆心空间,使图表更加轻量。只需将 radius 的第一项(内径)设为大于 0 的数值或百分比即可:
# 设置内外半径生成环形图
pie_donut = (
Pie()
.add(
series_name="业务占比",
data_pair=data_pair,
radius=["40%", "75%"], # 内径 40%,外径 75%
center=["50%", "50%"]
)
.set_global_opts(
title_opts=opts.TitleOpts(title="环形饼图展示", pos_left="center")
)
)
pie_donut.render("donut_pie.html")
2. 南丁格尔玫瑰图 (Rose Chart)
南丁格尔玫瑰图通过扇区的半径长度来区分数值大小,弧度角均等或依比例划分,能极大地增强视觉对比冲击力。关键参数为 rosette_type,可选值为 "radius"(扇区圆心角展现百分比,半径展现数据大小)或 "area"(所有扇区圆心角相同,仅通过半径展现数据大小):
# 南丁格尔玫瑰图
pie_rose = (
Pie()
.add(
series_name="成交量",
data_pair=data_pair,
radius=["20%", "75%"],
rosette_type="radius", # 启用玫瑰图模式
)
.set_global_opts(
title_opts=opts.TitleOpts(title="南丁格尔玫瑰图", pos_left="center")
)
)
pie_rose.render("rose_pie.html")
四、交互调优与视觉格式化技巧
为了让生成的图表在汇报或网页嵌入中具备更好的易读性,需要熟练掌握 Tooltip 格式化模板及标签排布控制。
1. 格式化占位符规则
在 ECharts 体系中,饼图内置了四个标准占位符:
{a}:系列名称(即add(series_name="...")指定的值)。{b}:数据项名称(即data_pair中每个元组的第一个元素)。{c}:数值(即data_pair中每个元组的第二个元素)。{d}:百分比(ECharts 引擎根据当前各项数值总和自动计算得出)。
示例配置:formatter="{b}: {c} 项 ({d}%)",在鼠标悬停时会精确显示类目名称、具体计数值及对应占比。
2. 图例交互与位置优化
当类目较多时,默认位于顶部的水平图例极易发生重叠。推荐使用垂直图例并放置于画布侧边:
legend_opts=opts.LegendOpts(
type_="scroll", # 当图例超长时支持上下滚动翻页
orient="vertical", # 垂直排列
pos_right="2%", # 靠右边距 2%
pos_top="20%", # 距离顶部 20%
)
五、常见问题排查与运行避坑
在实际开发过程中,初学者常因数据格式、资源加载或执行环境问题导致图表渲染失败。以下列出四大高频问题及标准解决方案:
1. 为什么报错 ValueError: not enough values to unpack?
这是最普遍的错误。原因在于错误地将一维列表传给了 data_pair。例如只传了 [10, 20, 30] 或分别传了两个参数。pyecharts 内部解析数据项时,每次循环迭代都要求取出一个键值对。务必确保传入的是形如 [("苹果", 50), ("橘子", 80)] 的结构。
2. 生成的 HTML 在浏览器中打开一片空白?
pyecharts 默认通过 CDN 引入外部 JavaScript 文件(如 echarts.min.js)。如果运行机器处于内网环境、无法连接公网或 CDN 遭受拦截,页面将无法加载渲染引擎导致空白。解决方案有两种:
- 离线静态资源替换:在代码最前引入全局配置,将静态文件指向本地服务器或国内 CDN 镜像:
from pyecharts.globals import CurrentConfig # 修改全局静态资源主机地址 CurrentConfig.ONLINE_HOST = "https://assets.pyecharts.org/assets/v5/" - 本地部署:安装
echarts-asset包并在本地启动静态资源服务。
3. 在 Jupyter Notebook 中无法正常显示?
在 Jupyter Notebook 或 JupyterLab 中运行时,不能调用 pie.render("output.html"),而应调用 pie.render_notebook()。并且初次加载前,需要确保前端插件能够正确加载依赖模块。
设计规范提醒:饼状图最适合展示 7 个以内的主要构成项。若分类超过 8 个,标签极易相互遮挡,读者对面积比例的辨识度也会显著下降。在实际业务中,建议将微小占比较多的项目归类求和为“其他”,从而保持图表整洁直观。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













