python-docx详细使用指南：用 Python 操作 Word 文档

python-docx 详细使用指南：用 Python 操作 Word 文档

python-docx 是一个功能强大的 Python 库，用于创建和更新 Microsoft Word (.docx) 文件。它允许你通过编程方式处理 Word 文档的各个方面，包括文本、段落、表格、图片、样式等。

1. 安装

首先，你需要安装 python-docx 库：

pip install python-docx

2. 文档的创建与打开

2.1 创建新文档

要创建一个全新的 Word 文档，只需实例化 Document 类：

from docx import Document

document = Document()
document.save('新文档.docx')
print("已创建一个名为 '新文档.docx' 的空文档。")

2.2 打开现有文档

如果你想修改一个已经存在的 Word 文档，可以将其路径传递给 Document 类：

from docx import Document

# 假设你有一个名为 '示例文档.docx' 的文件
try:
    document = Document('示例文档.docx')
    print("已成功打开 '示例文档.docx'。")
except Exception as e:
    print(f"打开文档时发生错误: {e}")

3. 添加标题

Word 文档中的标题可以通过 add_heading() 方法添加。你可以指定标题的文本内容和级别（从 0 到 9，其中 0 通常用于文档标题，1-9 对应 Word 中的“标题 1”到“标题 9”）。

from docx import Document

document = Document()

document.add_heading('这是一个文档主标题', level=0)
document.add_heading('一级标题', level=1)
document.add_heading('二级标题', level=2)
document.add_heading('三级标题', level=3)

document.save('带标题的文档.docx')
print("已创建 '带标题的文档.docx'，并添加了不同级别的标题。")

4. 添加段落

add_paragraph() 方法用于向文档中添加新的段落。你可以直接传入文本内容。

from docx import Document

document = Document()

document.add_paragraph('这是第一个段落的文本。')
document.add_paragraph('这是第二个段落的文本，它包含一些')
document.add_paragraph('分行显示的内容。')

document.save('带段落的文档.docx')
print("已创建 '带段落的文档.docx'，并添加了段落。")

4.1 段落的样式

你可以为段落指定样式。Word 内置了许多样式，如 ‘Normal’ (正文), ‘Intense Quote’ (强烈引用) 等。

from docx import Document

document = Document()

document.add_paragraph('这是一个普通段落。', style='Normal')
document.add_paragraph('这是一个引用段落。', style='Intense Quote')
document.add_paragraph('这是一个列表段落。', style='List Bullet')

document.save('带样式的段落文档.docx')
print("已创建 '带样式的段落文档.docx'，并为段落设置了样式。")

4.2 在段落中添加运行（Run）

段落是由一个或多个“运行”（Run）组成的。运行是具有相同格式（如字体、字号、颜色、粗体、斜体等）的文本序列。通过 add_run() 方法可以向段落中添加运行。

from docx import Document

document = Document()

paragraph = document.add_paragraph('这是一段')
run1 = paragraph.add_run('带有')
run1.bold = True  # 设置为粗体
run2 = paragraph.add_run('不同格式的')
run2.italic = True # 设置为斜体
run3 = paragraph.add_run('文本。')
run3.underline = True # 设置为下划线

# 可以设置字体、字号、颜色等
run1.font.name = 'Arial'
run1.font.size = docx.shared.Pt(12) # 12磅
run1.font.color.rgb = docx.shared.RGBColor(0x42, 0x24, 0xE9) # 蓝色

document.save('带运行的段落文档.docx')
print("已创建 '带运行的段落文档.docx'，展示了段落中不同格式的运行。")

5. 处理图片

add_picture() 方法用于向文档中插入图片。你需要提供图片文件的路径。你可以选择性地指定图片的宽度和高度。

from docx import Document
from docx.shared import Inches

document = Document()

# 创建一张示例图片用于演示
# 假设你有一个名为 'example_image.png' 的图片文件
# 如果没有，可以先生成一个简单的图片
try:
    # 尝试打开一个图片文件
    with open('example_image.png', 'rb') as f:
        pass
except FileNotFoundError:
    print("找不到 'example_image.png'。请确保图片文件存在或创建它。")
    # 为了演示，我们可以生成一个占位图片
    # from PIL import Image, ImageDraw
    # img = Image.new('RGB', (600, 400), color = 'red')
    # d = ImageDraw.Draw(img)
    # d.text((200,180), "Placeholder Image", fill=(255,255,0))
    # img.save('example_image.png')
    # print("已创建一个占位图片 'example_image.png'。")

# 确保 'example_image.png' 存在
# 假设我们已经有了一个 'example_image.png' 文件
document.add_picture('example_image.png', width=Inches(4)) # 设置宽度为 4 英寸

# 也可以设置宽度和高度
# document.add_picture('example_image.png', width=Inches(3), height=Inches(2))

document.save('带图片的文档.docx')
print("已创建 '带图片的文档.docx'，并插入了图片。")

这里提供一个简单的图片生成示例，如果你的环境中没有 Pillow 库，请先安装 pip install Pillow。

from PIL import Image, ImageDraw

def create_placeholder_image(filename='example_image.png', width=600, height=400):
    img = Image.new('RGB', (width, height), color = (73, 109, 137))
    d = ImageDraw.Draw(img)
    text = "Placeholder Image"
    textwidth, textheight = d.textsize(text, font=Image.open('arial.ttf')) # 需要一个字体文件
    x = (width - textwidth) / 2
    y = (height - textheight) / 2
    d.text((x,y), text, fill=(255,255,0))
    img.save(filename)
    print(f"已创建占位图片 '{filename}'。")

# 如果 'example_image.png' 不存在，则创建它
try:
    with open('example_image.png', 'rb') as f:
        pass
except FileNotFoundError:
    create_placeholder_image('example_image.png')

6. 处理表格

add_table() 方法用于向文档中添加表格。你需要指定行数和列数。

from docx import Document
from docx.shared import Inches

document = Document()

# 添加一个 3 行 3 列的表格
table = document.add_table(rows=3, cols=3)
table.autofit = False # 防止自动调整列宽

# 填充表头
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '姓名'
hdr_cells[1].text = '年龄'
hdr_cells[2].text = '城市'

# 填充数据
data = [
    ('张三', '25', '北京'),
    ('李四', '30', '上海'),
    ('王五', '22', '广州')
]

for row_data in data:
    row_cells = table.add_row().cells # 添加新行
    for i, text in enumerate(row_data):
        row_cells[i].text = text

# 可以设置表格样式 (Word内置样式，如 'Table Grid')
table.style = 'Table Grid'

# 调整列宽 (需要手动导入 Inchest)
# from docx.enum.table import WD_CELL_ALIGNMENT
# table.cell(0, 0).width = Inches(1.5)
# table.cell(0, 1).width = Inches(1)
# table.cell(0, 2).width = Inches(2)

document.save('带表格的文档.docx')
print("已创建 '带表格的文档.docx'，并插入了表格。")

7. 遍历文档内容

你可以遍历文档中的段落和表格来读取或修改它们的内容。

from docx import Document

document = Document('带标题的文档.docx') # 打开之前创建的文档

print("\n--- 文档内容遍历 ---")

for paragraph in document.paragraphs:
    print(f"段落: {paragraph.text}")

# 假设 '带表格的文档.docx' 存在
try:
    doc_with_table = Document('带表格的文档.docx')
    for table in doc_with_table.tables:
        print("\n--- 表格内容 ---")
        for row in table.rows:
            row_text = [cell.text for cell in row.cells]
            print("\t".join(row_text))
except Exception as e:
    print(f"处理表格文档时发生错误: {e}")

print("--- 遍历结束 ---")

8. 样式与格式化

python-docx 允许你对文档的各个部分进行详细的样式和格式化。

8.1 字体设置

你可以设置文本的字体、字号、颜色、粗体、斜体等。

from docx import Document
from docx.shared import Inches, Pt, RGBColor

document = Document()

paragraph = document.add_paragraph()
run = paragraph.add_run('这是一段自定义格式的文本。')

run.bold = True
run.italic = True
run.underline = True
run.font.name = 'Times New Roman'
run.font.size = Pt(16)
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00) # 红色

document.save('自定义格式文档.docx')
print("已创建 '自定义格式文档.docx'，并设置了文本格式。")

8.2 段落对齐

你可以设置段落的对齐方式（左对齐、居中、右对齐、两端对齐）。

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH

document = Document()

document.add_paragraph('这段文字是左对齐的。', style='Normal')

p_center = document.add_paragraph('这段文字是居中对齐的。')
p_center.alignment = WD_ALIGN_PARAGRAPH.CENTER

p_right = document.add_paragraph('这段文字是右对齐的。')
p_right.alignment = WD_ALIGN_PARAGRAPH.RIGHT

p_justify = document.add_paragraph('这段文字是两端对齐的。它会根据段落宽度自动调整单词间距，以使左右两端都对齐。')
p_justify.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

document.save('段落对齐文档.docx')
print("已创建 '段落对齐文档.docx'，并设置了段落对齐方式。")

9. 添加分页符和换行符

9.1 分页符

要在一个新页面上开始内容，可以添加一个分页符。

from docx import Document
from docx.enum.text import WD_BREAK

document = Document()

document.add_paragraph('这是第一页的内容。')
document.add_page_break() # 添加分页符
document.add_paragraph('这是第二页的内容。')

document.save('带分页符的文档.docx')
print("已创建 '带分页符的文档.docx'，并在文档中插入了分页符。")

9.2 换行符（Line Break）

在同一个段落中强制换行，而不是开始新段落。

from docx import Document
from docx.enum.text import WD_BREAK

document = Document()

p = document.add_paragraph()
p.add_run('这是第一行。')
p.add_run().add_break() # 添加换行符
p.add_run('这是第二行。')
p.add_run().add_break(WD_BREAK.LINE) # 显式指定为换行符
p.add_run('这是第三行。')

document.save('带换行符的文档.docx')
print("已创建 '带换行符的文档.docx'，并演示了段落内的换行。")

10. 高级应用：遍历和修改现有文档

python-docx 不仅可以创建新文档，还可以打开并修改现有文档。你可以遍历文档的 paragraphs 和 tables 属性来访问其内容。

10.1 替换文本

你可以遍历段落，找到特定文本并进行替换。

from docx import Document

# 假设 '示例文档.docx' 包含要替换的文本
# 创建一个示例文档
document = Document()
document.add_paragraph('Hello, world! This is a sample document.')
document.add_paragraph('We want to replace "world" with "Python".')
document.save('替换示例文档.docx')

doc = Document('替换示例文档.docx')

for paragraph in doc.paragraphs:
    if 'world' in paragraph.text:
        # docx库没有直接的段落文本替换方法，需要操作run
        # 更简单的方法是重新构建段落的run
        # 但这会丢失原有run的格式，所以需要更精细的控制

        # 暴力替换（会丢失原有格式）
        # paragraph.text = paragraph.text.replace('world', 'Python')

        # 精细替换（保留原有格式）
        # 这是一个更复杂的任务，需要遍历run并替换
        # 下面是一个简化示例，如果原文只有简单run，可以直接替换
        new_text = paragraph.text.replace('world', 'Python')
        paragraph.clear() # 清空原有运行
        paragraph.add_run(new_text) # 添加新的运行

doc.save('替换后的文档.docx')
print("已创建并替换 '替换示例文档.docx' 中的文本为 '替换后的文档.docx'。")

关于文本替换的注意事项：

python-docx 在处理文本替换时，由于 Word 文档的复杂结构（段落由多个 run 组成，每个 run 可以有不同的格式），直接修改 paragraph.text 会导致所有原有 run 的格式丢失。

更健壮的替换方法需要：
1. 遍历段落中的所有 run。
2. 将 run 的文本拼接起来形成完整段落文本。
3. 对完整段落文本进行替换。
4. 清空原有段落的所有 run。
5. 根据替换后的文本和原有的格式（如果需要）重新创建 run。
这通常需要更复杂的逻辑来解析和应用原有格式。对于简单的替换，上面示例中的 paragraph.clear() 和 paragraph.add_run(new_text) 足够。

11. 总结和最佳实践

• 保存文档： 任何修改后都必须调用 document.save('filename.docx') 来保存更改。
• 样式优先： 尽量使用 Word 内置或自定义的样式来格式化文档，而不是对每个 run 或 paragraph 进行手动格式化。这样可以保持文档的一致性，并且更容易维护。
• 英寸和点： python-docx 使用 docx.shared.Inches 和 docx.shared.Pt 来表示长度和字体大小，这有助于保持单位的准确性。
• 枚举类型： docx.enum 模块提供了各种枚举类型，如 WD_ALIGN_PARAGRAPH 用于段落对齐，WD_BREAK 用于分页符等。使用它们可以提高代码的可读性和健壮性。
• 理解文档结构： Word 文档的结构是：Document -> Paragraphs / Tables -> Runs / Cells。理解这种层次结构有助于你更有效地操作文档。