Python pyecharts生成交互式饼状图代码

闻溪
闻溪
发布时间:2026-11-17 | 12人浏览过
原创

使用 Python pyecharts 库生成交互式饼状图的完整教程与代码示例,涵盖基础饼图、环形图、南丁格尔玫瑰图的配置方法及常见排错指南。

在 Python 数据可视化中,想要生成支持鼠标悬停浮动提示、图例联动切换、动态扇区高亮及缩放过滤的交互式饼状图,基于 Apache ECharts 封装的开源库 pyecharts 是高效实用的选择。与 Matplotlib 或 Seaborn 生成静态位图不同,pyecharts 通过 Python 构建配置并直接渲染出包含原生 JavaScript 交互逻辑的独立 HTML 文件。本文提供从环境依赖安装、最简可运行示例,到环形图、南丁格尔玫瑰图定制及高频问题排查的完整指南。

Python pyecharts生成交互式饼状图代码
缩略图:pyecharts 饼状图核心功能与应用形态概览

一、环境准备与依赖安装

在编写代码前,需要确保系统中已安装 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 类构建。在底层逻辑上,数据必须以“二元序列”(即每个元素为 (名称, 数值) 或 [名称, 数值] 的列表)形式传入。构建流程包括数据准备、类目实例化、配置项装配和渲染四个环节。

Python pyecharts生成交互式饼状图代码
图 1:pyecharts 交互式饼图生成机制与流程拆解

以下是生成标准交互式饼状图的完整可执行代码:

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")
Python pyecharts生成交互式饼状图代码
图 2:生成交互式饼状图的 4 个核心操作步骤

三、常见衍生形态:环形图与南丁格尔玫瑰图

在实际业务中,单一的实心饼图容易在大面积显示时产生视觉疲劳。通过调整 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")
Python pyecharts生成交互式饼状图代码
图 3:三种典型饼状图形态及其关键参数配置对比

四、交互调优与视觉格式化技巧

为了让生成的图表在汇报或网页嵌入中具备更好的易读性,需要熟练掌握 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%
)

五、常见问题排查与运行避坑

在实际开发过程中,初学者常因数据格式、资源加载或执行环境问题导致图表渲染失败。以下列出四大高频问题及标准解决方案:

Python pyecharts生成交互式饼状图代码
图 4:交互式饼图开发关键要素与常见陷阱排查指南

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 个,标签极易相互遮挡,读者对面积比例的辨识度也会显著下降。在实际业务中,建议将微小占比较多的项目归类求和为“其他”,从而保持图表整洁直观。

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表