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