PythonPPT制作
Python 文档处理实战：python-docx 库详解与应用
python-docx 是 Python 生态中用于读写 Microsoft Word 文档的核心库。本文系统讲解该库的安装配置、基础文档构建、文本样式控制、表格与图片操作、页面布局设置及邮件合并功能。通过多个完整代码示例，演示如何自动化生成复杂报告、批量处理文档数据，并提供性能优化建议与常见错误排查方案，助力开发者实现办公文档的自动化处理。
python-docx 是 Python 生态中用于读写 Microsoft Word 文档的核心库。本文系统讲解该库的安装配置、基础文档构建、文本样式控制、表格与图片操作、页面布局设置及邮件合并功能。通过多个完整代码示例，演示如何自动化生成复杂报告、批量处理文档数据，并提供性能优化建议与常见错误排查方案，助力开发者实现办公文档的自动化处理。
Microsoft Word 是最常用的文档处理工具之一，但在企业级应用和自动化运维场景中，经常需要以编程方式生成、修改或提取 Word 文档内容。Python 提供了强大的 python-docx 库，它允许开发者在无需安装 Microsoft Office 的情况下，创建、编辑和操作 .docx 格式的文档。本文将深入解析 python-docx 的核心用法，涵盖从基础文档构建到高级排版功能的完整流程。
在使用 python-docx 之前，确保已安装 Python 环境（推荐 3.6 及以上版本）。通过 pip 包管理器进行安装：
pip install python-docx
如果网络受限，可使用国内镜像源加速下载：
pip install python-docx -i https://pypi.tuna.tsinghua.edu.cn/simple
python-docx 基于 Office Open XML 标准。理解其对象层级对于高效开发至关重要：
创建一个新文档非常简单，只需实例化 Document 类：
from docx import Document
# 创建空白文档
doc = Document()
# 添加标题（级别 0 为一级标题，1 为二级标题，以此类推）
doc.add_heading('Python 文档处理示例', level=0)
# 添加普通段落
doc.add_paragraph('这是一个使用 python-docx 创建的 Word 文档示例。')
# 保存文档
doc.save('example.docx')
python-docx 支持丰富的文本样式控制，包括字体、大小、颜色、加粗、斜体等。
from docx.shared import Pt
from docx.oxml.ns import qn
p = doc.add_paragraph()
# 加粗文本
run_bold = p.add_run('这是加粗的文本。')
run_bold.bold = True
# 斜体文本
run_italic = p.add_run('这是斜体的文本。')
run_italic.italic = True
# 下划线
run_underline = p.add_run('这是带下划线的文本。')
run_underline.underline = True
# 设置字体大小为 14 磅
run_size = p.add_run('这是 14 号字体。')
run_size.font.size = Pt(14)
# 设置字体颜色（RGB）
# 注意：qn 函数用于指定 XML 命名空间
from docx.shared import RGBColor
run_color = p.add_run('这是红色的文本。')
run_color.font.color.rgb = RGBColor(255, 0, 0)
# 设置中文字体（如微软雅黑）
run_cn = p.add_run('这是中文字体。')
run_cn.font.name = '微软雅黑'
run_cn._element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑')
表格是文档中常见的元素，python-docx 提供了灵活的表格处理能力。
from docx.shared import Inches
# 创建 3 行 3 列的表格
table = doc.add_table(rows=3, cols=3)
table.style = 'Table Grid' # 应用预设样式
# 填充数据
for i in range(3):
for j in range(3):
cell = table.cell(i, j)
cell.text = f'单元格 ({i}, {j})'
# 合并单元格
# 合并第一行的前两个单元格
cell_top_left = table.cell(0, 0)
cell_top_mid = table.cell(0, 1)
cell_top_left.merge(cell_top_mid)
虽然 python-docx 对边框的直接控制有限，但可以通过样式或底层 XML 进行修改。通常建议使用内置样式。
插入图片时需注意路径问题。支持相对路径和绝对路径。
from docx.shared import Inches
# 插入本地图片，设置宽度和高度
doc.add_picture('images/logo.png', width=Inches(4), height=Inches(3))
# 如果图片不存在，会抛出 FileNotFoundError
try:
doc.add_picture('non_existent.png')
except FileNotFoundError:
print("图片文件未找到")
from docx.shared import Cm
section = doc.sections[0]
section.left_margin = Cm(2.5)
section.right_margin = Cm(2.5)
section.top_margin = Cm(3)
section.bottom_margin = Cm(3)
section.page_width = Cm(21) # A4 宽度
section.page_height = Cm(29.7) # A4 高度
section.orientation = docx.enum.text.WD_PAGE_ORIENTATION.LANDSCAPE
from docx.enum.text import WD_BREAK
doc.add_page_break()
页眉和页脚是文档的重要组成部分，常用于显示公司 Logo、页码或日期。
header = doc.sections[0].header
footer = doc.sections[0].footer
# 设置页眉
header_paragraph = header.paragraphs[0]
header_paragraph.add_run('公司名称').bold = True
# 设置页脚
footer_paragraph = footer.paragraphs[0]
footer_paragraph.add_run('第 ')
footer_paragraph.add_run('{page}') # 注意：实际页码需通过域代码或特定方式更新，此处仅为占位
footer_paragraph.add_run(' 页')
from docx.oxml.ns import qn
p = doc.add_paragraph()
run = p.add_run('点击访问官网')
run.hyperlink.document_reference = 'http://www.example.com'
run.font.color.rgb = RGBColor(0, 0, 255)
run.font.underline = True
bookmark = doc.bookmarks.add('MyBookmark')
bookmark.paragraph.add_run('这里是书签位置')
邮件合并允许将数据源（如 Excel 或 CSV）与 Word 模板结合，批量生成个性化文档。
import pandas as pd
# 读取数据源
df = pd.read_excel('data.xlsx')
# 加载模板
template_doc = Document('template.docx')
# 遍历每一行数据
for index, row in df.iterrows():
# 替换模板中的占位符
for paragraph in template_doc.paragraphs:
if '${name}' in paragraph.text:
paragraph.text = paragraph.text.replace('${name}', row['name'])
# 保存为新文档
new_doc = Document(template_doc)
new_doc.save(f'report_{index}.docx')
在处理大型文档时，建议使用上下文管理器或显式关闭资源，防止内存泄漏。
尽量使用 styles 对象而非直接设置 font 属性，这样生成的文档更符合 Word 规范，且易于后期维护。
style = doc.styles['Normal']
font = style.font
font.name = 'Times New Roman'
font.size = Pt(12)
生成的 .docx 文件在不同版本的 Word 中可能显示略有差异。建议在目标环境中测试最终效果。
python-docx 是一个功能丰富且强大的工具，适用于自动化文档生成、报告创建及办公文档的批量处理。通过掌握上述基础与高级功能，开发者可以显著提高工作效率，减少重复性手工操作。无论是需要自动创建周报、生成合同，还是进行复杂的文档数据处理，python-docx 都能成为得力的技术助手。
在实际项目中，建议结合 pandas 处理数据，结合 reportlab 处理 PDF，形成完整的文档处理工作流。同时，注意异常处理和日志记录，确保脚本在生产环境中的稳定性。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online