python-docx API详解：从Document类到Table对象的全面参考

【免费下载链接】python-docx Create and modify Word documents with Python 项目地址: https://gitcode.com/gh_mirrors/py/python-docx

python-docx是一个强大的Python库，用于创建和修改Word文档。本文将深入解析其核心API，从基础的Document类到复杂的Table对象，帮助你快速掌握用Python操作Word文档的精髓。

一、Document类：文档操作的起点

Document类是python-docx的核心，代表一个Word文档。通过它可以创建新文档、添加内容和设置格式。

1.1 创建和保存文档

使用docx.Document()创建新文档，或打开现有文档。完成编辑后，调用save()方法保存到指定路径：

from docx import Document

# 创建新文档
doc = Document()
# 保存文档
doc.save('example.docx')

1.2 文档基本操作

Document类提供了丰富的方法来操作文档内容：

• add_heading(text, level): 添加标题，level范围0-9（0为标题样式，1-9为Heading 1-9）
• add_paragraph(text, style): 添加段落，可指定样式
• add_page_break(): 添加分页符
• add_picture(image_path, width, height): 添加图片
• add_table(rows, cols, style): 添加表格

1.3 访问文档内容

通过以下属性可以访问文档中的元素：

• paragraphs: 文档中所有段落的列表
• tables: 文档中所有表格的列表
• sections: 文档中所有节的列表
• styles: 文档中所有样式的集合

核心实现代码位于src/docx/document.py。

二、Table对象：表格操作全指南

表格是Word文档中常用的元素，python-docx提供了强大的Table对象来处理表格。

2.1 创建表格

使用Document.add_table(rows, cols, style)方法创建表格：

# 创建3行4列表格
table = doc.add_table(rows=3, cols=4, style='Table Grid')

2.2 表格基本操作

Table类提供了多种方法操作表格结构：

• add_row(): 在表格末尾添加一行
• add_column(width): 在表格右侧添加一列
• cell(row_idx, col_idx): 获取指定单元格

2.3 单元格操作

每个单元格是一个_Cell对象，可以像操作迷你文档一样操作单元格内容：

# 获取第一行第一列单元格
cell = table.cell(0, 0)
# 设置单元格文本
cell.text = "标题"
# 向单元格添加段落
cell.add_paragraph("单元格内容")

单元格还支持合并操作，使用merge(other_cell)方法可以合并多个单元格：

# 合并第一行前两列单元格
cell_1 = table.cell(0, 0)
cell_2 = table.cell(0, 1)
cell_1.merge(cell_2)

2.4 表格样式设置

可以通过style属性设置表格样式，通过alignment属性设置表格对齐方式：

# 设置表格样式
table.style = "Light Shading Accent 1"
# 设置表格居中对齐
table.alignment = WD_TABLE_ALIGNMENT.CENTER

表格相关实现代码位于src/docx/table.py。

三、实战技巧：高效使用python-docx

3.1 文档样式管理

利用styles属性可以管理文档中的样式，确保格式统一：

# 获取所有段落样式
paragraph_styles = [s for s in doc.styles if s.type == WD_STYLE_TYPE.PARAGRAPH]

3.2 图片处理

添加图片时，可以指定宽度和高度，保持图片比例：

# 添加图片并设置宽度
doc.add_picture('features/steps/test_files/mountain.bmp', width=Inches(5))

3.3 表格数据处理

可以将Python列表数据快速导入表格：

data = [
    ["姓名", "年龄", "职业"],
    ["张三", "30", "工程师"],
    ["李四", "28", "设计师"]
]

for row_idx, row_data in enumerate(data):
    for col_idx, cell_data in enumerate(row_data):
        table.cell(row_idx, col_idx).text = cell_data

四、总结

python-docx提供了从Document到Table的完整API，让你能够用Python轻松创建和修改Word文档。无论是简单的文本编辑还是复杂的表格操作，都能通过直观的API实现。通过灵活运用这些API，你可以自动化生成报告、创建模板、处理数据等多种任务。

要深入学习python-docx，可以参考项目中的官方文档和测试案例，不断探索更多高级功能。

【免费下载链接】python-docx Create and modify Word documents with Python 项目地址: https://gitcode.com/gh_mirrors/py/python-docx