使用 Python 在 Word 文档中创建图表

在现代办公自动化场景中，将数据可视化为图表并嵌入 Word 文档已成为一项常见需求。无论是生成销售报告、制作数据分析文档，还是创建项目进度汇报，programmatically 在 Word 中插入图表都能显著提升工作效率。本文将深入探讨如何使用 Python 在 Word 文档中创建各种类型的图表，并对其进行样式定制和数据配置。

可通过 pip 安装：pip install spire.doc.free。

环境准备

本文所使用的示例基于 Free Spire.Doc for Python，在开始之前，需要安装该库。可通过 pip 安装：

pip install spire.doc.free

安装完成后，即可在 Python 脚本中导入相关模块开始工作。

基础架构：文档与图表对象模型

在使用 Spire.Doc 创建图表前，需要了解其基本的对象层次结构：

1. Document：表示整个 Word 文档
2. Section：文档中的节，用于组织内容
3. Paragraph：段落，用于承载文本和图表等元素
4. Shape：形状对象，图表作为特殊形状嵌入其中
5. Chart：图表对象，包含数据系列、坐标轴、标题等属性

基本操作流程为：创建文档 → 添加节 → 添加段落 → 插入图表形状 → 配置图表数据 → 保存文档。

创建第一个图表：柱形图

柱形图是最常用的图表类型之一，适合比较不同类别的数据。以下示例展示了如何创建一个简单的柱形图：

from spire.doc import *
from spire.doc.common import *

# 创建文档对象
document = Document()

# 添加一个节
section = document.AddSection()

# 添加标题段落
section.AddParagraph().AppendText("Column chart.")

# 添加新段落用于放置图表
newPara = section.AddParagraph()

# 插入柱形图，指定宽度和高度（单位为点）
shape = newPara.AppendChart(ChartType.Column, float(500), float(300))

# 获取图表对象
chart = shape.Chart

# 清空默认的数据系列
chart.Series.Clear()

# 添加数据系列：名称、X 轴类别、Y 轴数值
chart.Series.Add("Test Series",
                 ["Word", "PDF", "Excel", "GoogleDocs", "Office"],
                 [float(1900000), float(850000), float(2100000), 
                  float(600000), float(1500000)])

# 设置 Y 轴数字格式
chart.AxisY.NumberFormat.FormatCode = "#,##0"

# 保存文档
document.SaveToFile("ColumnChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

关键点解析：

• AppendChart() 方法接受三个参数：图表类型枚举、宽度、高度
• Series.Add() 方法用于添加数据系列，需要提供类别标签和对应的数值
• 数值需要转换为 float 类型以确保兼容性
• AxisY.NumberFormat.FormatCode 控制 Y 轴标签的显示格式

条形图：水平数据对比

条形图是柱形图的水平版本，特别适合类别名称较长或需要强调排名关系的场景：

# 创建条形图
chartShape = newPara.AppendChart(ChartType.Bar, float(400), float(300))
chart = chartShape.Chart

# 获取并设置图表标题
title = chart.Title
title.Text = "My Chart"
title.Show = True
title.Overlay = True  # 标题覆盖在图表上方

# 保存文档
document.SaveToFile("BarChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

标题的三个关键属性：

• Text：标题显示的文本内容
• Show：是否显示标题
• Overlay：True 时标题覆盖在图表区域上，False 时标题位于图表外部

饼图：占比分析

饼图适合展示各部分占整体的比例关系，在财务分析和市场份额报告中应用广泛：

# 创建饼图
shape = newPara.AppendChart(ChartType.Pie, 500.0, 300.0)
chart = shape.Chart

# 添加单个数据系列（饼图通常只需要一个系列）
series = chart.Series.Add("Test Series", 
                          ["Word", "PDF", "Excel"],
                          [2.7, 3.2, 0.8])

# 保存文档
document.SaveToFile("PieChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

饼图的特点：

• 通常只使用一个数据系列
• 每个数据点代表整体中的一个部分
• 扇区大小由数值比例决定

折线图：趋势展示

折线图擅长展示数据随时间或其他连续变量的变化趋势：

# 创建折线图
shape = newPara.AppendChart(ChartType.Line, 500.0, 300.0)
chart = shape.Chart

# 获取标题对象并设置
title = chart.Title
title.Text = "My Chart"

# 清空默认系列
seriesColl = chart.Series
seriesColl.Clear()

# 定义 X 轴类别
categories = ["C1", "C2", "C3", "C4", "C5", "C6"]

# 添加多个数据系列进行对比
seriesColl.Add("AW Series 1", categories, 
               [1.0, 2.0, 2.5, 4.0, 5.0, 6.0])
seriesColl.Add("AW Series 2", categories, 
               [2.0, 3.0, 3.5, 6.0, 6.5, 7.0])

# 保存文档
document.SaveToFile("LineChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

折线图的关键特性：

• 支持多个数据系列叠加显示
• 适合展示时间序列数据
• 可以清晰对比不同系列的趋势差异

散点图：相关性分析

散点图用于展示两个变量之间的关系，在统计分析和科学研究中经常使用：

# 创建散点图
shape = newPara.AppendChart(ChartType.Scatter, 450.0, 300.0)
chart = shape.Chart

# 清空默认系列
chart.Series.Clear()

# 添加数据系列：X 值、Y 值
chart.Series.Add("Scatter chart", 
                 [1.0, 2.0, 3.0, 4.0, 5.0],
                 [1.0, 20.0, 40.0, 80.0, 160.0])

# 保存文档
document.SaveToFile("ScatterChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

散点图的特点：

• 每个数据点由 X 和 Y 两个坐标值确定
• 适合发现变量间的相关性模式
• 可用于回归分析和趋势预测

气泡图：三维数据可视化

气泡图是散点图的扩展，通过气泡大小展示第三个维度的数据：

# 创建气泡图
shape = newPara.AppendChart(ChartType.Bubble, float(500), float(300))
chart = shape.Chart

# 清空默认系列
chart.Series.Clear()

# 添加数据系列：X 值、Y 值、气泡大小
series = chart.Series.Add("Test Series", 
                          [2.9, 3.5, 1.1, 4.0, 4.0],
                          [1.9, 8.5, 2.1, 6.0, 1.5],
                          [9.0, 4.5, 2.5, 8.0, 5.0])

# 保存文档
document.SaveToFile("BubbleChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

气泡图的独特之处：

• 同时展示三个维度的数据
• 气泡大小与第三个数值成正比
• 适合复杂的多变量分析场景

3D 曲面图：立体数据展示

3D 曲面图提供立体的数据可视化效果，适合展示地形、温度分布等连续表面数据：

# 创建 3D 曲面图
shape = newPara.AppendChart(ChartType.Surface3D, 500.0, 300.0)
chart = shape.Chart

# 清空默认系列
chart.Series.Clear()

# 设置图表标题
chart.Title.Text = "My chart"

# 添加多个数据系列
chart.Series.Add("Series 1", 
                 ["Word", "PDF", "Excel", "GoogleDocs", "Office"],
                 [1900000.0, 850000.0, 2100000.0, 600000.0, 1500000.0])

chart.Series.Add("Series 2", 
                 ["Word", "PDF", "Excel", "GoogleDocs", "Office"],
                 [900000.0, 50000.0, 1100000.0, 400000.0, 2500000.0])

chart.Series.Add("Series 3", 
                 ["Word", "PDF", "Excel", "GoogleDocs", "Office"],
                 [500000.0, 820000.0, 1500000.0, 400000.0, 100000.0])

# 保存文档
document.SaveToFile("Surface3DChart.docx", FileFormat.Docx)
document.Dispose()

结果预览：

3D 曲面图的特点：

• 提供立体的视觉呈现
• 支持多个数据系列叠加
• 适合展示复杂的多维度数据关系

图表尺寸与定位

图表的尺寸和位置对于文档的整体布局至关重要。AppendChart() 方法的第二和第三个参数分别控制图表的宽度和高度，单位为点（point）：

• 1 点 = 1/72 英寸 ≈ 0.35 毫米
• 常用尺寸：400x300（小型）、500x300（中型）、600x400（大型）

定位技巧：

# 在特定段落后插入图表
para = section.AddParagraph()
para.Format.SpaceAfter = 20  # 设置段后间距

# 插入图表
chartShape = para.AppendChart(ChartType.Column, float(500), float(300))

通过调整段落的间距属性，可以控制图表与周围文字的间隔，实现美观的排版效果。

数据系列管理

数据系列是图表的核心组成部分。Spire.Doc 提供了灵活的系列操作方法：

添加系列

# 添加单个系列
chart.Series.Add("系列名称", ["类别 1", "类别 2"], [100.0, 200.0])

# 添加多个系列
chart.Series.Add("系列 A", categories, valuesA)
chart.Series.Add("系列 B", categories, valuesB)

清空系列

在添加自定义数据前，通常需要清空默认的系列：

chart.Series.Clear()

访问系列集合

可以通过 Series 属性访问系列集合进行更复杂的操作：

seriesColl = chart.Series
# 对系列集合进行操作

坐标轴格式化

坐标轴的显示格式直接影响图表的可读性。Spire.Doc 允许对坐标轴进行精细的格式控制：

# 设置 Y 轴数字格式（千位分隔）
chart.AxisY.NumberFormat.FormatCode = "#,##0"

# 设置百分比格式
chart.AxisY.NumberFormat.FormatCode = "0%"

# 设置小数位数
chart.AxisY.NumberFormat.FormatCode = "0.00"

常见的格式代码：

• #,##0：千位分隔符，无小数
• 0.00：保留两位小数
• 0%：百分比格式
• $#,##0：美元货币格式

完整实战示例

以下是一个综合示例，展示了如何在实际项目中创建包含多种图表的报告文档：

from spire.doc import *
from spire.doc.common import *

def create_sales_report():
    # 创建文档
    doc = Document()
    section = doc.AddSection()
    
    # 添加标题
    title_para = section.AddParagraph()
    title_para.AppendText("2024 Sales Report")
    title_para.Format.HorizontalAlignment = ShapeHorizontalAlignment.Center
    
    # 添加柱形图
    section.AddParagraph().AppendText("\nQuarterly Sales:")
    col_para = section.AddParagraph()
    col_chart = col_para.AppendChart(ChartType.Column, float(500), float(300))
    col_chart.Chart.Series.Clear()
    col_chart.Chart.Series.Add("Sales", 
                               ["Q1", "Q2", "Q3", "Q4"],
                               [150000.0, 220000.0, 180000.0, 250000.0])
    col_chart.Chart.AxisY.NumberFormat.FormatCode = "$#,##0"
    
    # 添加饼图
    section.AddParagraph().AppendText("\nProduct Distribution:")
    pie_para = section.AddParagraph()
    pie_chart = pie_para.AppendChart(ChartType.Pie, float(400), float(300))
    pie_chart.Chart.Series.Add("Products",
                               ["Product A", "Product B", "Product C"],
                               [45.0, 35.0, 20.0])
    
    # 保存文档
    doc.SaveToFile("Sales_Report.docx", FileFormat.Docx)
    doc.Dispose()

create_sales_report()

结果预览：

常见问题与解决方案

图表显示不完整

确保段落的行距设置适当，避免图表被裁剪：

para.Format.LineUnitAfter = 1  # 增加段后行距

数据精度问题

始终将数值显式转换为 float 类型：

values = [float(x) for x in raw_values]

中文标签显示

Spire.Doc 完全支持 Unicode 字符，可以直接使用中文字符串作为类别标签或标题。

总结

在 Word 文档中 programmatically 创建图表是办公自动化的重要技能。通过掌握 Spire.Doc for Python 提供的图表 API，可以实现：

1. 创建七种主要图表类型：柱形图、条形图、饼图、折线图、散点图、气泡图、3D 曲面图
2. 灵活配置数据系列和坐标轴格式
3. 精确控制图表尺寸和位置
4. 批量生成包含图表的专业报告文档

关键要点回顾：

• 使用 AppendChart() 方法插入图表，指定类型和尺寸
• 通过 Series.Add() 添加数据，记得先调用 Clear() 清空默认数据
• 利用 NumberFormat.FormatCode 格式化坐标轴标签
• 合理设置图表尺寸，确保在文档中的显示效果

掌握这些技能后，你可以进一步探索图表标题样式、图例位置、数据标签、颜色主题等高级定制功能，构建出功能完备的文档自动化生成系统。

更多 Word 文档操作技巧，请前往 Spire.Doc for Python 官方教程查看。