在 Python 应用中，通过代码生成 Word 文档是一种非常常见的需求。无论是报表、发票、合同、审计日志，还是数据导出结果，很多场景都需要以 可编辑的 .docx 文件 形式交付，而不仅仅是纯文本或 PDF。

与简单的文本输出不同，Word 文档本质上是一个结构化文档，由节（Section）、段落（Paragraph）、样式（Style）以及各种版式规则共同组成。如果在生成 Word 文档时，仅将 .docx 当作“文本容器”来处理，往往会在内容增长后出现排版混乱、维护困难等问题。

本文将围绕 使用 Python 实际创建 Word 文档 这一主题展开，基于 Spire.Doc for Python 进行讲解，重点说明如何按照 Word 原生的文档对象模型构建内容，在正确的结构层级上应用格式与布局，并确保在文档内容不断扩展的情况下，仍然能够生成结构稳定、易于编辑的 .docx 文件。

内容概览

• 1. 理解 Python 中的 Word 文档结构
• 2. 使用 Python 创建基础 Word 文档
• 3. 添加与格式化文本内容
• 4. 向 Word 文档中插入图片
• 5. 创建并填充表格
• 6. 添加页眉和页脚
• 7. 使用节控制页面布局
• 8. 设置文档属性与元数据
• 9. 保存、导出与性能注意事项
• 10. 使用 Python 创建 Word 文档时的常见问题

1. Python 中的 Word 文档结构解析

在开始编写代码之前，理解 Word 文档在内部是如何组织的非常重要。

.docx 文件并不是一段线性的文本流，而是由多个具有明确职责的对象层级组成，包括：

• Document（文档）：整个 Word 文件的根容器
• Section（节）：定义页面级别的布局，例如页面大小、页边距、方向
• Paragraph（段落）：表示一个逻辑上的文本块
• Run / TextRange（文本范围）：段落中的行内文本片段，用于控制字符级格式
• Style（样式）：可复用的格式定义，用于统一段落或文本的外观

当你在 Python 中创建 Word 文档时，本质上是在通过代码显式构建这一层级结构。只有在正确的层级上添加内容和设置格式，文档的布局和行为才能保持可预测性。

Spire.Doc for Python 为这些核心概念提供了直接的抽象，使你可以按照 Word 本身的工作方式来操作文档结构，而不是通过“拼文本”的方式生成文件。

2. 使用 Python 创建基础 Word 文档

本节将演示如何使用 Spire.Doc 在 Python 中生成一个有效的 Word 文档，重点放在正确的文档结构和基本流程上。

安装 Spire.Doc for Python

pip install spire.doc

你也可以从官网下载并手动集成： 下载 Spire.Doc for Python

创建一个简单的 .docx 文件

from spire.doc import Document, FileFormat

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

# 添加一个节（定义页面级布局）
section = document.AddSection()

# 向节中添加段落
paragraph = section.AddParagraph()
paragraph.AppendText(
    "该文档由使用  Spire.Doc for Python 生成，"
    "展示创建 Word 文档基础步骤。"
)

# 保存文档
document.SaveToFile("basic_document.docx", FileFormat.Docx)
document.Close()

该示例生成了一个最小但合法的 .docx 文件，可以直接在 Microsoft Word 中打开。整体流程包括：

1. 创建文档对象
2. 添加节
3. 在节中插入段落和文本
4. 保存文件

从技术角度来看：

• Document 表示整个 Word 文件结构，并负责管理所有内容
• Section 提供页面级布局环境
• Paragraph 承载实际显示的文本，是所有段落级格式的基本单位

使用 Spire.Doc 创建的所有 Word 文档，都遵循这一结构模式，这也是后续更高级操作的基础。

3. 添加与格式化文本内容

Word 文档中的文本是分层组织的，格式设置也存在明确的层级区分：

• 段落级格式：用于控制对齐方式、段前段后间距、缩进等
• 字符级格式：用于控制字体、字号、颜色、加粗、斜体等
• 样式（Style）：用于集中存储上述格式配置，以便在多个位置重复使用

理解段落格式、字符格式与样式之间的区别，是使用 Python 创建或编辑 Word 文档的关键。

添加文本并设置段落格式

Word 文档中的所有可见文本，都必须通过段落添加。段落不仅是文本的容器，也是布局控制的基本单位。

• 段落级格式通过 Paragraph.Format 设置
• 字符级格式通过 TextRange.CharacterFormat 设置

from spire.doc import Document, HorizontalAlignment, FileFormat, Color

document = Document()
section = document.AddSection()

# 添加标题段落
title = section.AddParagraph()
title.Format.HorizontalAlignment = HorizontalAlignment.Center
title.Format.AfterSpacing = 20
title.Format.BeforeSpacing = 20
title_range = title.AppendText("月度销售报告")
title_range.CharacterFormat.FontSize = 18
title_range.CharacterFormat.Bold = True
title_range.CharacterFormat.TextColor = Color.get_LightBlue()
title_range.CharacterFormat.FontName = "黑体"

# 添加正文段落
body = section.AddParagraph()
body.Format.FirstLineIndent = 20
body_range = body.AppendText(
    "本报告提供了月度销售业绩概览，"
    "包括各地区和产品类别的收入趋势。"
    "下方数据旨在为管理层的决策提供支持。"
)
body_range.CharacterFormat.FontSize = 12

document.SaveToFile("formatted_paragraph.docx", FileFormat.Docx)
document.Close()

生成的 Word 文档效果如下：

技术要点说明：

• Paragraph.Format 控制整个段落的布局
• AppendText() 返回 TextRange，用于设置字符级格式
• 每个段落都必须隶属于某个节，段落顺序决定阅读顺序和分页结果

创建并应用样式

样式可以将段落和字符的格式集中定义并复用，从而提高一致性和可维护性。Word 同时支持自定义样式和内置样式，使用前都需要将样式添加到文档中。

创建并应用自定义段落样式

from spire.doc import (
    Document, HorizontalAlignment, BuiltinStyle,
    TextAlignment, ParagraphStyle, FileFormat
)

document = Document()

# 创建自定义段落样式
custom_style = ParagraphStyle(document)
custom_style.Name = "CustomStyle"
custom_style.ParagraphFormat.HorizontalAlignment = HorizontalAlignment.Center
custom_style.ParagraphFormat.TextAlignment = TextAlignment.Auto
custom_style.CharacterFormat.Bold = True
custom_style.CharacterFormat.FontSize = 20

# 继承内置标题样式
custom_style.ApplyBaseStyle(BuiltinStyle.Heading1)

# 添加样式到文档
document.Styles.Add(custom_style)

# 应用样式
title_para = document.AddSection().AddParagraph()
title_para.ApplyStyle(custom_style.Name)
title_para.AppendText("地区业绩概览")

添加并使用内置样式

built_in_style = document.AddStyle(BuiltinStyle.Heading2)
document.Styles.Add(built_in_style)

heading_para = document.Sections.get_Item(0).AddParagraph()
heading_para.ApplyStyle(built_in_style.Name)
heading_para.AppendText("按地区销售情况")

document.SaveToFile("document_styles.docx", FileFormat.Docx)

技术说明：

• ParagraphStyle(document) 创建与文档关联的可复用样式
• ParagraphFormat 控制布局属性
• CharacterFormat 定义字体相关属性
• ApplyBaseStyle() 可继承 Word 内置样式的语义与行为
• 将样式添加到 document.Styles 后，才能在整个文档中使用

使用内置样式（如 Heading 2）可以确保文档在目录生成、大纲视图等 Word 功能中保持良好兼容性。

4. 向 Word 文档中插入图片

在 Word 的文档模型中，图片是附属于段落的嵌入对象。这种设计可以确保图片与文本一起参与排版，并在内容变化时自动调整位置。

在段落中插入图片

from spire.doc import Document, TextWrappingStyle, HorizontalAlignment, FileFormat

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\n示例图片\r\n")

image_para = section.AddParagraph()
image_para.Format.HorizontalAlignment = HorizontalAlignment.Center
image = image_para.AppendPicture("Screen.jpg")

image.TextWrappingStyle = TextWrappingStyle.Square
image.Width = 350
image.Height = 200
image.FillTransparency(0.7)
image.HorizontalAlignment = HorizontalAlignment.Center

document.SaveToFile("document_images.docx", FileFormat.Docx)

技术细节说明：

• AppendPicture() 将图片作为段落内容插入
• TextWrappingStyle 控制文本环绕方式
• Width 与 Height 设置显示尺寸
• FillTransparency() 设置透明度
• HorizontalAlignment 控制图片在段落中的对齐方式

将图片插入段落中，可以确保图片尺寸变化时分页自动调整、文本编辑后排版仍然正确，同时导出为 PDF 等格式时保持相对位置一致。

更多 Word 文档图片操作介绍请查看：使用 Python 在 Word 文档中插入图片

5. 创建并填充表格

表格常用于展示结构化数据，例如统计报表、汇总信息或对比结果。

在 Word 的内部结构中，一个表格由行（Row）、单元格（Cell）组成，而每个单元格本身仍然是段落容器，可以包含文本、图片或其他格式化内容。

在 Word 文档中创建并格式化表格

from spire.doc import Document, DefaultTableStyle, FileFormat, AutoFitBehaviorType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\n示例表格\r\n")

# 表头数据
table_headers = ["地区", "产品", "销售数量", "单价（元）", "总收入（元）"]
table_data = [
    ["华北", "笔记本电脑", 120, 9500, 1140000],
    ["华北", "智能手机", 300, 5000, 1500000],
    ["华南", "笔记本电脑", 80, 9500, 760000],
    ["华南", "智能手机", 200, 5000, 1000000],
    ["华东", "笔记本电脑", 150, 9500, 1425000],
    ["华东", "智能手机", 250, 5000, 1250000],
    ["西南", "笔记本电脑", 100, 9500, 950000],
    ["西南", "智能手机", 220, 5000, 1100000]
]

# 向节中添加表格
table = section.AddTable()
table.ResetCells(len(table_data) + 1, len(table_headers))

# 填充表头
for col_index, header in enumerate(table_headers):
    header_range = table.Rows[0].Cells[col_index].AddParagraph().AppendText(header)
    header_range.CharacterFormat.FontSize = 14
    header_range.CharacterFormat.Bold = True

# 填充表格数据
for row_index, row_data in enumerate(table_data):
    for col_index, cell_data in enumerate(row_data):
        data_range = table.Rows[row_index + 1].Cells[col_index].AddParagraph().AppendText(str(cell_data))
        data_range.CharacterFormat.FontSize = 12

# 应用默认表格样式并自动调整列宽
table.ApplyStyle(DefaultTableStyle.ColorfulListAccent6)
table.AutoFit(AutoFitBehaviorType.AutoFitToContents)

document.SaveToFile("document_tables.docx", FileFormat.Docx)

生成的 Word 文档预览如下：

技术要点说明：

• Section.AddTable() 将表格插入到节的内容流中
• ResetCells(rows, columns) 明确定义表格的行列结构
• Table.Rows[row].Cells[col] 返回一个 TableCell 对象

在 Word 中，每个单元格都是一个独立的内容容器。文本始终通过段落插入，而单元格内可以包含多个段落、图片或格式化文本。这种结构使表格既可以用于简单数据展示，也可以扩展为复杂的报表布局。

如果需要更高级的表格操作（如动态生成表格、合并单元格、单元格级格式控制等），可参考完整指南： 使用 Python 在 Word 文档中创建表格

6. 添加页眉和页脚

在 Word 中，页眉和页脚属于节级元素，不参与正文内容流，也不会影响正文分页。

每一个节都可以拥有独立的页眉和页脚，这使得文档不同部分可以显示不同的重复信息。

在节中添加页眉和页脚

from spire.doc import Document, FileFormat, HorizontalAlignment, FieldType, BreakType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendBreak(BreakType.PageBreak)

# 添加页眉
header = section.HeadersFooters.Header

header_para1 = header.AddParagraph()
header_para1.AppendText("月度销售报告").CharacterFormat.FontSize = 12
header_para1.Format.HorizontalAlignment = HorizontalAlignment.Left

header_para2 = header.AddParagraph()
header_para2.AppendText("公司名称").CharacterFormat.FontSize = 12
header_para2.Format.HorizontalAlignment = HorizontalAlignment.Right

# 添加页脚（页码）
footer = section.HeadersFooters.Footer
footer_para = footer.AddParagraph()
footer_para.Format.HorizontalAlignment = HorizontalAlignment.Center
footer_para.AppendText("第 ").CharacterFormat.FontSize = 12
footer_para.AppendField("PageNum", FieldType.FieldPage).CharacterFormat.FontSize = 12
footer_para.AppendText(" 页，共 ").CharacterFormat.FontSize = 12
footer_para.AppendField("NumPages", FieldType.FieldNumPages).CharacterFormat.FontSize = 12
footer_para.AppendText(" 页").CharacterFormat.FontSize = 12

document.SaveToFile("document_header_footer.docx", FileFormat.Docx)
document.Dispose()

生成的文档效果如下：

技术说明：

• section.HeadersFooters.Header / Footer 用于访问当前节的页眉和页脚
• AppendField() 可插入动态字段，如当前页码和总页数

页眉和页脚通常用于显示报表标题、公司信息和页码，并且在文档内容发生变化时会自动更新，同时兼容 Word、PDF 等导出格式。

更多高级示例可参考： 使用 Python 向 Word 文档中插入页眉和页脚

7. 使用节（Section）控制页面布局

在 Spire.Doc for Python 中，所有页面级布局设置都通过 Section 对象进行管理。页面大小、方向和页边距均由 Section.PageSetup 控制，并对该节内的所有内容生效。

设置页面大小和方向

from spire.doc import PageSize, PageOrientation

section.PageSetup.PageSize = PageSize.A4()
section.PageSetup.Orientation = PageOrientation.Portrait

技术说明：

• PageSetup 是节级布局配置对象
• PageSize 定义页面的物理尺寸
• Orientation 控制纵向或横向排版

节中的所有段落、表格和图片都会遵循该布局设置。修改某一节的页面设置不会影响文档中的其他节，因此可以在同一文档中使用多种页面布局。

设置页边距

section.PageSetup.Margins.Top = 50
section.PageSetup.Margins.Bottom = 50
section.PageSetup.Margins.Left = 60
section.PageSetup.Margins.Right = 60

技术说明：

• Margins 定义正文的可打印区域
• 页边距以文档内部单位进行设置

页边距在节级别统一生效，不需要针对单个段落单独设置，并且不会影响页眉和页脚区域。

使用多个节实现不同布局

当文档需要混合不同页面布局时，必须创建多个节。

landscape_section = document.AddSection()
landscape_section.PageSetup.Orientation = PageOrientation.Landscape

技术要点：

• AddSection() 会创建并追加一个新的节
• 每个节拥有独立的页面设置、页眉和页脚
• 该方法之后添加的内容都会属于新节

通过多节结构，可以在同一 Word 文档中混合纵向与横向页面，或为不同内容区域应用不同版式。

8. 设置文档属性与元数据

除了可见内容之外，Word 文档还支持通过内置文档属性存储元数据。这些属性位于文档级别，不会影响页面布局或渲染效果。

设置内置文档属性

document.BuiltinDocumentProperties.Title = "Monthly Sales Report"
document.BuiltinDocumentProperties.Author = "Data Analytics System"
document.BuiltinDocumentProperties.Company = "Example Corp"

技术说明：

• BuiltinDocumentProperties 用于访问 Word 的标准文档属性
• 可设置的属性包括 Title、Author、Company 等

文档属性常用于文件索引、搜索、文档管理系统和审计流程。除了内置属性外，Word 还支持 关键词、主题、备注、超链接基地址 等元数据，也可以通过 Document.CustomDocumentProperties 定义自定义属性。

更多内容可参考： 使用 Python 管理 Word 文档的自定义属性

9. 保存、导出与性能注意事项

在内存中构建好 Word 文档之后，最后一步是将其保存或导出为目标格式。Spire.Doc for Python 提供统一的 API 支持多种导出格式，可在不额外修改文档结构的情况下复用同一份内容。

以多种格式保存和导出文档

from spire.doc import FileFormat

document.SaveToFile("output.docx", FileFormat.Docx)
document.SaveToFile("output.pdf", FileFormat.PDF)
document.SaveToFile("output.html", FileFormat.Html)
document.SaveToFile("output.rtf", FileFormat.Rtf)

导出过程会保留文档结构，包括节、表格、图片、页眉和页脚，从而在不同格式中保持一致的布局效果。完整支持的格式列表可参考： FileFormat 枚举说明

文档生成的性能优化建议

在高频或大规模生成 Word 文档的场景下，可以通过以下方式提升性能：

• 复用文档模板和样式
• 避免不必要的节创建
• 在所有内容生成完成后再统一写入磁盘
• 保存或导出后，显式调用 document.Close() 释放资源

当需要批量生成结构相同但数据不同的文档时，邮件合并（Mail Merge） 通常比逐个手动插入内容更高效。Spire.Doc for Python 内置了邮件合并功能，适用于大规模文档生成场景。

参考示例： 使用 Python 通过邮件合并批量生成 Word 文档

10. 使用 Python 创建 Word 文档时的常见问题

在通过代码生成 Word 文档的过程中，以下问题较为常见，尤其容易出现在对 Word 文档结构理解不足的情况下。

将 Word 文档当作纯文本处理

问题表现： 随着内容长度变化，原有格式被破坏，排版不可控。

改进建议： 始终基于节（Section）、段落（Paragraph）和样式（Style）来构建文档结构，而不是简单地插入原始文本。

在代码中硬编码格式逻辑

问题表现： 当需要调整整体版式或字体风格时，必须在多个代码位置逐一修改，维护成本高。

改进建议： 通过样式和节级布局配置集中管理格式规则，避免在业务代码中重复定义格式细节。

忽略节（Section）的边界

问题表现： 修改页边距或页面方向后，意外影响了整个文档的布局。

改进建议： 使用多个节来隔离不同的页面布局设置，确保各部分互不干扰。

11. 总结

使用 Python 创建 Word 文档 并不仅仅是向文件中写入文本。.docx 文件本质上是由节、段落、样式以及各种嵌入对象组成的结构化文档。

通过 Spire.Doc for Python，并按照 Word 原生的文档模型来组织代码，你可以生成结构清晰、可编辑性良好、且在内容和布局变化时依然稳定的 Word 文档。这种方式尤其适合后端服务、报表生成流程以及文档自动化系统。

在涉及大型文档生成或文档转换等场景时，通常需要使用**授权版本**以获得完整功能支持。