当前位置：首页 > news >正文

python-docx 库教程

news 2025/6/13 18:08:42

Python-docx 库介绍

官网文档
python-docx 是一个用于创建和修改 Microsoft Word (.docx) 文件的 Python 库。它允许你通过编程方式生成格式化的文档，添加文本、段落、表格、图片等元素，而无需依赖 Microsoft Word 应用程序。

主要功能

创建新的 Word 文档
添加段落、标题和列表
设置文本格式（字体、大小、颜色、加粗、斜体等）
插入表格和处理表格数据
添加图片和图表
管理文档样式和布局
读取和修改现有文档

安装 python-docx 库：当前版本1.1.2

pip install python-docx==1.1.2

一，基本使用示例

docx_basics.py

from docx import Document
from docx.shared import Pt, Inches
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT# 创建新文档
doc = Document()# 添加标题
doc.add_heading('Python-docx示例文档', 0)# 添加段落
paragraph = doc.add_paragraph('这是一个使用python-docx库创建的示例文档。')# 添加带有格式的文本
paragraph.add_run(' 这部分文本是粗体').bold = True
paragraph.add_run('，这部分是斜体').italic = True# 添加不同级别的标题
doc.add_heading('一级标题', level=1)
doc.add_heading('二级标题', level=2)# 添加列表
doc.add_paragraph('无序列表项', style='List Bullet')
doc.add_paragraph('有序列表项', style='List Number')# 添加表格
table = doc.add_table(rows=1, cols=3)
table.alignment = WD_TABLE_ALIGNMENT.CENTER
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '姓名'
hdr_cells[1].text = '年龄'
hdr_cells[2].text = '职业'# 添加表格数据
row_cells = table.add_row().cells
row_cells[0].text = '张三'
row_cells[1].text = '30'
row_cells[2].text = '工程师'# 添加图片
doc.add_picture('example.png', width=Inches(4))# 保存文档
doc.save('demo.docx')

docx_reading.py

from docx import Document# 打开现有文档
doc = Document('existing_document.docx')# 读取所有段落
for para in doc.paragraphs:print(para.text)# 修改段落
if len(doc.paragraphs) > 0:doc.paragraphs[0].text = '这是修改后的第一段内容'# 访问表格
if len(doc.tables) > 0:table = doc.tables[0]for row in table.rows:for cell in row.cells:print(cell.text)# 添加新内容
doc.add_paragraph('这是添加到现有文档的新段落')# 保存修改
doc.save('modified_document.docx')

文档样式和格式设置

docx_styles.py

from docx import Document
from docx.shared import Pt, RGBColor
from docx.enum.text import WD_PARAGRAPH_ALIGNMENTdoc = Document()# 设置段落格式
paragraph = doc.add_paragraph('这是一个居中对齐的段落，字体为12磅，颜色为蓝色。')
paragraph.alignment = WD_PARAGRAPH_ALIGNMENT.CENTER# 设置文本格式
run = paragraph.runs[0]
run.font.name = 'Arial'
run.font.size = Pt(12)
run.font.color.rgb = RGBColor(0, 0, 255)  # 蓝色
run.bold = True
run.italic = True# 创建自定义样式
style = doc.styles.add_style('MyHeading', 1)  # 1表示标题样式
style.font.name = '微软雅黑'
style.font.size = Pt(16)
style.font.bold = True# 使用自定义样式
doc.add_heading('自定义样式标题', level=1).style = doc.styles['MyHeading']doc.save('styled_document.docx')

限制和注意事项

python-docx 只能处理.docx格式的文件，不能处理旧版的.doc格式
对于复杂的 Word 文档（如包含高级格式、复杂图表或特殊效果），可能无法完全复制其格式
某些 Word 功能（如脚注、尾注、复杂的页眉页脚）的支持有限
该库主要关注文档内容的操作，对于文档的布局和打印设置支持较少

二， Python-docx 库的类结构

python-docx 库基于 Open XML 标准构建，采用层次化的类结构来表示 Word 文档的各个组件。主要类及其关系如下：

Document：代表整个 Word 文档，是所有其他元素的容器
Section：文档的节，可包含不同的页面设置
Paragraph：段落，包含文本和格式信息
Run：文本运行，共享相同格式的文本块
Table：表格，由行和单元格组成
TableStyle：表格样式
Style：文档样式
Header/Footer：页眉和页脚
Image：图片对象

这些类之间的关系是嵌套的：Document 包含多个 Section，每个 Section 包含多个 Paragraph 和 Table，而 Paragraph 又由一个或多个 Run 组成。

常用类和方法详解

Document 类
创建和打开文档：

from docx import Document# 创建新文档
doc = Document()# 打开现有文档
doc = Document('existing_document.docx')# 保存文档
doc.save('new_document.docx')

添加内容：

# 添加段落
doc.add_paragraph('这是一个新段落')# 添加标题
doc.add_heading('这是一级标题', level=1)# 添加分页符
doc.add_page_break()

Paragraph 类
段落操作：

# 获取段落
paragraphs = doc.paragraphs  # 获取所有段落
first_para = doc.paragraphs[0]  # 获取第一个段落# 添加段落
paragraph = doc.add_paragraph('初始文本')# 添加文本到段落
paragraph.add_run('额外的文本')# 设置段落格式
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER  # 居中对齐
paragraph.paragraph_format.line_spacing = 1.5  # 1.5倍行距

Run 类
文本格式设置：

# 创建带有格式的文本
run = paragraph.add_run('这是粗体斜体文本')
run.bold = True
run.italic = True
run.font.size = Pt(12)
run.font.color.rgb = RGBColor(255, 0, 0)  # 红色
run.font.name = 'Arial'

Table 类
表格操作：

# 添加表格
table = doc.add_table(rows=3, cols=3)# 访问单元格
cell = table.cell(0, 0)  # 第一行第一列
cell.text = '单元格内容'# 遍历表格
for row in table.rows:for cell in row.cells:print(cell.text)# 设置表格样式
table.style = 'Table Grid'

样式操作
应用和创建样式：

# 应用现有样式
paragraph.style = doc.styles['Heading 1']# 创建自定义样式
from docx.shared import Pt
from docx.enum.style import WD_STYLE_TYPEstyle = doc.styles.add_style('MyStyle', WD_STYLE_TYPE.PARAGRAPH)
style.font.name = 'Arial'
style.font.size = Pt(12)
style.font.bold = True

图片和媒体
插入图片：

from docx.shared import Inches# 添加图片
doc.add_picture('image.jpg', width=Inches(4))

页眉和页脚
页眉页脚操作：

# 获取第一个节的页眉
header = doc.sections[0].header# 添加内容到页眉
header.paragraphs[0].text = '这是页眉'# 获取页脚
footer = doc.sections[0].footer
footer.paragraphs[0].text = '这是页脚'

示例：创建复杂文档，包含多种元素文档的完整示例

complex_document.py

from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.style import WD_STYLE_TYPE# 创建文档
doc = Document()# 添加标题
title = doc.add_heading('示例文档', level=0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER# 添加段落
doc.add_paragraph('这是一个使用python-docx创建的示例文档。')# 添加带格式的段落
paragraph = doc.add_paragraph('这是一个包含 ')
paragraph.add_run('粗体').bold = True
paragraph.add_run(' 和 ')
paragraph.add_run('斜体').italic = True
paragraph.add_run(' 文本的段落。')# 添加图片
doc.add_picture('sample.jpg', width=Inches(4))# 添加表格
table = doc.add_table(rows=1, cols=3)
table.style = 'Table Grid'# 设置表头
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '项目'
hdr_cells[1].text = '描述'
hdr_cells[2].text = '价格'# 添加数据行
data = [('产品A', '这是产品A的描述', '$100'),('产品B', '这是产品B的描述', '$200'),('产品C', '这是产品C的描述', '$300')
]for item, desc, price in data:row_cells = table.add_row().cellsrow_cells[0].text = itemrow_cells[1].text = descrow_cells[2].text = price# 添加分页符
doc.add_page_break()# 添加列表
doc.add_paragraph('项目列表:', style='List Bullet')
doc.add_paragraph('项目1', style='List Bullet 2')
doc.add_paragraph('项目2', style='List Bullet 2')# 添加自定义样式
style = doc.styles.add_style('MyQuote', WD_STYLE_TYPE.PARAGRAPH)
style.base_style = doc.styles['Quote']
style.font.size = Pt(11)
style.font.italic = True# 使用自定义样式
doc.add_paragraph('这是一个引用段落', style='MyQuote')# 保存文档
doc.save('complex_document.docx')