Python Matplotlib绘制饼状图基础代码与参数详解

一、快速上手：基础饼状图的构建流程

使用 Matplotlib 绘制饼状图遵循明确的线性开发步骤。最基础的调用仅需提供一组数值序列。plt.pie() 会自动汇总序列所有元素之和，并根据各元素数值占总和的相对比例计算对应扇形的圆心角，因此用户无需事先手动将原始数据归一化为百分比。

下面是一段最小可运行的基础绘图代码：

# 最小可运行基础示例
import matplotlib.pyplot as plt

# 1. 准备分类数据与标签
data = [35, 25, 20, 20]
labels = ['研发支出', '市场推广', '运营运维', '行政开销']

# 2. 绘制基础饼图
plt.pie(data, labels=labels)

# 3. 锁定坐标轴比例为正圆
plt.axis('equal')

# 4. 显示图表
plt.show()

在上述代码中，两个关键细节需要特别留意：

• labels 的对应关系：标签列表的长度必须与数据列表严格保持一致，索引位置一一对应。
• plt.axis('equal') 的必要性：Matplotlib 默认生成的绘图区域通常为矩形画布，如果不主动设置坐标轴纵横比相等，绘制出的圆形可能会被水平或垂直拉伸为椭圆。

二、核心参数详解与功能拆解

要让饼状图满足生产级报表的要求，必须借助 plt.pie() 提供的丰富参数对数值精度、空间相对位置和视觉层级进行精细控制。以下拆解最常用的核心参数及其配置逻辑。

1. autopct 与 pctdistance（百分比数值标注）

默认情况下，饼图只绘制扇区，不显示具体百分比。autopct 参数用于在扇区内部自动标注所占百分比：

• 格式化字符串模式：最常用的是 autopct='%1.1f%%'，其中 %1.1f 表示保留一位小数的浮点数，末尾两个 %% 转义输出一个百分号字符。若需要保留整数，可写为 '%d%%'。
• 函数或 lambda 表达式模式：如果希望不仅显示百分比，还同时打印该扇区的原始绝对数值，可以给 autopct 传递一个接受百分比浮点值作为入参的可调用函数。
• pctdistance 控制半径：浮点数，默认值为 0.6。它表示数值标注距离圆心的距离占整个半径的比例（0 为圆心，1.0 为饼图边缘）。若调为 0.75，数字更靠近外边缘。

2. explode（突出指定扇区）

explode 参数用于将一个或多个扇形沿半径方向向外移动，从而产生“切块弹出”的视觉聚焦效果：

• 其取值为一个长度与数据项相等的元组或列表，元素为浮点数（偏移半径比例）。
• 例如 explode=(0.1, 0, 0, 0) 表示仅将第一项向外平移半径的 10%，其余扇形保持贴合圆心不动。

3. startangle 与 counterclock（起始角度与旋转方向）

默认情况下，Matplotlib 的起始位置为水平向右的 X 轴正方向（0 度），并按照逆时针方向顺次排布扇区：

• startangle：接收一个角度数值。在数据报表中，最符合人眼直觉的排版是从正上方（即时钟 12 点钟方向）顺次展开，因此工程中常设为 startangle=90。
• counterclock：布尔值，默认为 True（逆时针）。设为 False 即可改为顺时针排列。

4. colors 与 wedgeprops（色彩方案与扇区属性）

自定义色彩和边框能大幅提升图表的专业度：

• colors：传入十六进制颜色代码或命名颜色列表，如 ['#6487A5', '#C28B68', '#3B536B', '#D8B296']。
• wedgeprops：接收一个字典，直接传递给底层的 matplotlib.patches.Wedge 对象。常用键包括 'edgecolor'（扇区边缘线颜色，常用纯白 '#FFFFFF'）与 'linewidth'（边缘线宽）。此外，设置 'width' 参数是构造环形图的核心手段。

5. labels、labeldistance 与 textprops（文字标签与样式控制）

• labeldistance：分类标签距离圆心的相对半径，默认值为 1.1（即位于饼图外缘之外稍作悬浮）。
• textprops：用于统一定制标签文字的字体字典，例如 textprops={'fontsize': 11, 'color': '#2C3E50'}。

三、进阶实战：高定制化饼图与环形图（Donut Chart）

在现代商业智能（BI）看板和科技报告中，环形图（Donut Chart）越来越受到青睐。环形图通过在中心挖空一个同心圆，将读者对面积的估算转移到对外周圆弧长度的对比上，感知更加敏锐；同时，中心腾出的空间可以直观展示核心 KPI 或总数指标。

在 Matplotlib 中制作环形图极为简洁，只需在 wedgeprops 中加入 'width': 0.4（表示扇环宽度占总半径的 40%，中心留出 60% 镂空），无需额外绘制白色覆盖圆。下面是包含中文字体配置、阴影描边与中心文字的完整进阶代码：

import matplotlib.pyplot as plt

# 1. 解决中文显示方块与负号异常问题
plt.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'SimHei']
plt.rcParams['axes.unicode_minus'] = False

# 2. 准备业务数据（建议按降序排列）
categories = ['云原生服务', '大数据分析', 'AI与算法', '网络安全']
revenue = [4200, 2800, 1800, 1200]
theme_colors = ['#6487A5', '#C28B68', '#3B536B', '#D8B296']

# 3. 创建画布
fig, ax = plt.subplots(figsize=(7, 6), subplot_kw=dict(aspect="equal"))

# 4. 绘制环形图 (设置 wedgeprops 的 width 属性)
wedges, texts, autotexts = ax.pie(
    revenue,
    labels=categories,
    autopct='%1.1f%%',
    pctdistance=0.78,
    startangle=90,
    counterclock=False,
    colors=theme_colors,
    wedgeprops=dict(width=0.38, edgecolor='white', linewidth=2),
    textprops=dict(color='#2C3E50', fontsize=11)
)

# 5. 微调百分比文本颜色（内部文本浅色显示增强对比）
for at in autotexts:
    at.set_color('white')
    at.set_fontsize(10.5)
    at.set_weight('bold')

# 6. 在环形图正中心添加总金额指标说明
total_val = sum(revenue)
ax.text(0, 0.08, '总营收', ha='center', va='center', fontsize=13, color='#748391')
ax.text(0, -0.10, f'¥{total_val:,}', ha='center', va='center', fontsize=16, weight='bold', color='#2C3E50')

# 7. 标题与布局
plt.title('企业核心产品线营收构成', fontsize=15, pad=20, color='#2C3E50', weight='bold')
plt.tight_layout()
plt.show()

四、常见问题排查与工程最佳实践

在实际项目落地中，除了参数调用外，开发者经常遇到几个高频痛点。以下是针对性排查策略与工程建议：

五、总结

掌握 plt.pie() 的核心在于“形”与“意”的协调：

1. 数据输入层面：依赖 x 自动比例化，结合排序与分类合并，保证扇区数量克制（5 到 7 个以内）；
2. 排版定位层面：通过 startangle=90 和 counterclock=False 建立自上而下的顺畅视觉流，借助 pctdistance 和 labeldistance 区分内外层信息；
3. 视觉表现层面：善用 wedgeprops 绘制白色细分割线，或者赋予 'width' 参数将实体饼图升维为信息密度更高的环形图，并用中心留白承载全局总量。

通过这套系统化的参数组合，即可在 Python 中高效产出结构严谨、可读性强的数据可视化作品。