在现代办公自动化场景中，将数据可视化为图表并嵌入 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 创建图表前，需要了解其基本的对象层次结构：
- Document：表示整个 Word 文档
- Section：文档中的节，用于组织内容
- Paragraph：段落，用于承载文本和图表等元素
- Shape：形状对象，图表作为特殊形状嵌入其中
- 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，可以实现：
- 创建七种主要图表类型：柱形图、条形图、饼图、折线图、散点图、气泡图、3D 曲面图
- 灵活配置数据系列和坐标轴格式
- 精确控制图表尺寸和位置
- 批量生成包含图表的专业报告文档
关键要点回顾：
- 使用
AppendChart() 方法插入图表，指定类型和尺寸 - 通过
Series.Add() 添加数据，记得先调用 Clear() 清空默认数据 - 利用
NumberFormat.FormatCode 格式化坐标轴标签 - 合理设置图表尺寸，确保在文档中的显示效果
掌握这些技能后，你可以进一步探索图表标题样式、图例位置、数据标签、颜色主题等高级定制功能，构建出功能完备的文档自动化生成系统。
更多 Word 文档操作技巧，请前往 Spire.Doc for Python 官方教程查看。
