这是一个专门用于创建、修改和读取 Microsoft Word (.docx) 文件的库，它功能强大，可以满足绝大多数自动化 Word 文档生成的需求。
（图片来源网络，侵删）
什么是 python-docx？
python-docx 是一个开源的 Python 库，它允许你以编程方式操作 Word 文档，你需要注意的是，它不能处理旧版的 .doc 文件，只能处理基于 Office Open XML 格式的 .docx 文件。
它的核心思想是：将一个 Word 文档看作一个由不同部分组成的对象集合，比如文档本身、段落、表格、图片、样式等,你可以通过创建和修改这些对象来构建你的文档。
安装
使用 pip 安装非常简单：
pip install python-docx
核心概念：文档结构
要熟练使用 python-docx，首先要理解它如何组织一个 Word 文档：
（图片来源网络，侵删）
Document: 代表整个 Word 文档,这是你操作的入口点。Paragraph(段落): 文档中的文本块，通常以回车键结束，一个段落可以包含一个或多个Run。Run(文本块): 段落中具有相同格式（如字体、大小、颜色、加粗等）的连续文本,这是应用样式的最小单位。Block(块级元素): 段落和表格都是文档中的块级元素,它们按顺序排列。Table(表格): 由行和列组成的结构。Text(文本): 最基本的文本内容。
常用操作示例
下面我们通过一些代码示例来学习最常见的操作。
示例 1：创建一个新文档并添加基本内容
这是最简单的例子，创建一个新文档,添加一个标题和几个段落。
import docx
# 1. 创建一个新的文档对象
doc = docx.Document()
# 2. 添加一个标题 (add_heading 简化了标题的添加)
doc.add_heading('Python-Docx 示例文档', level=1) # level=1 是一级标题
# 3. 添加一个段落
p = doc.add_paragraph('这是一个由 python-docx 库创建的段落。')
p.add_run(' 这部分文本是同一个段落中的新 Run，我们可以单独设置它的样式。').bold = True # 将新添加的文本设为粗体
# 4. 添加另一个带样式的段落
doc.add_paragraph('这是一个二级标题', style='Heading 2')
doc.add_paragraph('这是一个普通段落。')
# 5. 保存文档
doc.save('my_document.docx')
print("文档 'my_document.docx' 已创建。")
示例 2：添加列表
有序列表和无序列表也很容易实现。
import docx
doc = docx.Document()
doc.add_heading('列表示例', level=2)
# 添加一个无序列表
doc.add_paragraph('项目一', style='List Bullet')
doc.add_paragraph('项目二', style='List Bullet')
doc.add_paragraph('项目三', style='List Bullet')
# 添加一个有序列表
doc.add_paragraph('第一项', style='List Number')
doc.add_paragraph('第二项', style='List Number')
doc.add_paragraph('第三项', style='List Number')
doc.save('list_example.docx')
示例 3：添加表格
创建和填充表格是常见需求。
（图片来源网络，侵删）
import docx
doc = docx.Document()
doc.add_heading('表格示例', level=2)
# 添加一个 3行4列 的表格
table = doc.add_table(rows=3, cols=4)
# 填充表头
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '姓名'
hdr_cells[1].text = '年龄'
hdr_cells[2].text = '城市'
hdr_cells[3].text = '职业'
# 填充数据行
for i in range(1, 3):
row_cells = table.rows[i].cells
row_cells[0].text = f'用户 {i}'
row_cells[1].text = f'{25 + i}'
row_cells[2].text = f'城市 {i}'
row_cells[3].text = f'工程师'
doc.save('table_example.docx')
示例 4：添加图片
添加图片需要指定图片的路径和宽度（可选，高度会自动按比例调整）。
import docx
doc = docx.Document()
doc.add_heading('图片示例', level=2)
# 假设你有一张名为 'my_image.png' 的图片在当前目录下
try:
doc.add_picture('my_image.png', width=docx.shared.Inches(4.0)) # 宽度设为4英寸
print("图片添加成功。")
except FileNotFoundError:
print("错误：未找到 'my_image.png' 图片文件，请确保图片在正确的路径下。")
doc.save('image_example.docx')
示例 5：读取和修改现有文档
python-docx 不仅能创建，还能读取和修改已有的 .docx 文件。
import docx
# 打开一个已有的文档
try:
doc = docx.Document('my_document.docx') # 确保这个文件存在
# 1. 遍历所有段落并打印内容
print("--- 文档中的所有段落 ---")
for para in doc.paragraphs:
print(para.text)
# 2. 修改第一个段落
if doc.paragraphs:
first_para = doc.paragraphs[0]
# 检查第一个 Run 是否存在，避免错误
if first_para.runs:
first_para.runs[0].text = "这是被修改过的标题！"
first_para.runs[0].bold = True
else:
first_para.text = "这是被修改过的标题！"
# 3. 在文档末尾添加新内容
doc.add_paragraph('这是在读取现有文档后添加的新段落。')
# 4. 保存修改 (保存时会覆盖原文件，建议先备份)
doc.save('modified_document.docx')
print("\n文档 'my_document.docx' 已被修改并保存为 'modified_document.docx'。")
except FileNotFoundError:
print("错误：未找到 'my_document.docx' 文件，请先运行示例1创建它。")
高级功能
-
页面设置: 可以设置页边距、纸张方向等。
from docx.shared import Inches, Pt from docx.enum.section import WD_ORIENT sections = doc.sections section = sections[0] section.left_margin = Inches(1.0) section.right_margin = Inches(1.0) section.orientation = WD_ORIENT.LANDSCAPE # 设置为横向
-
字体和样式: 可以精确控制文本的字体、大小、颜色、下划线等。
from docx.shared import RGBColor p = doc.add_paragraph() run = p.add_run('这是一段有样式的文本。') run.font.name = 'Calibri' run.font.size = Pt(14) run.font.bold = True run.font.italic = True run.font.color.rgb = RGBColor(255, 0, 0) # 设置为红色 -
页眉和页脚: 可以方便地添加和修改页眉页脚。
section = doc.sections[0] footer = section.footer footer_para = footer.paragraphs[0] footer_para.text = "这是页脚内容"
重要注意事项
.docx格式: 再次强调，python-docx只能处理.docx文件，不支持.doc。- 样式继承: 当你打开一个已有的
.docx文件时，文档中所有的样式（如自定义的标题样式、字体样式）都会被加载，你可以在代码中引用这些已有的样式名（如style='My Custom Style'）。 - 覆盖保存: 当你使用
save()方法时，如果文件名已存在，它会被直接覆盖，在修改重要文件前,请务必备份。 - 性能: 对于包含大量内容（如成百上千页）的文档，
python-docx的性能可能会下降，但对于绝大多数报告、合同、模板等场景,它的性能是完全足够的。
python-docx 是一个功能强大且易于使用的 Python 库，非常适合用于自动化 Word 文档的生成和修改，无论是生成简单的报告、批量创建证书，还是基于模板生成复杂的文档，它都能胜任，掌握其核心的 Document、Paragraph 和 Run 概念，你就可以高效地处理各种 Word 文档任务。
