Python3 模块精讲｜python-docx 万字实战：全自动读写 Word 文档，办公效率直接翻倍

qq_283720052026-04-27 9:04

文章标签：#Python #python-docx #办公自动化 #Word 处理 #Python 实战

📝 本章学习目标：本章聚焦 Python 办公自动化最强刚需技能，帮助读者从零到一完全掌握python-docx模块的创建、读取、修改、样式、表格、图片、批量生成等全套能力。通过本章学习，你将能独立完成企业级 Word 自动化任务，把重复工作交给代码，1 分钟顶 1 小时人工。

一、引言：为什么 python-docx 是职场必备神器

在数据分析、报告输出、合同生成、报表自动化等场景中，Word 文档处理是每天都要面对的工作。手动复制、粘贴、排版、改格式不仅效率极低，还极易出错。python-docx 的出现，让 Python 直接操控 Word 成为现实，彻底解放双手。

1.1 背景与意义

💡 核心认知：python-docx 是目前 Python 生态最稳定、最通用、最易用 的 Word 文档处理库，专门处理 .docx 格式（Word 2007 及以上版本）。它可以实现：文本增删改、标题段落、字体样式、表格操作、图片插入、页面设置、批量生成、模板替换等几乎所有 Word 常用功能。

据行业数据显示，75% 以上的办公自动化项目依赖 python-docx，能把人工几十分钟甚至几小时的排版、填表、做报告工作，压缩到几秒内完成，是职场提效的核心利器。

1.2 本章结构概览

为了让你系统性掌握 python-docx，本章严格按以下路线递进学习：

plaintext

复制代码 
📊 环境安装 → 核心概念 → 写入文档 → 读取文档 → 样式设置 → 表格图片 → 修改文档 → 批量实战 → 最佳实践 → 常见问题 → 总结展望

二、核心概念解析

2.1 基本定义

概念一：python-docx 核心能力清单

表格

能力 说明 典型应用场景
创建文档 新建空白 docx 文档 自动周报、月报、总结
写入内容 段落、标题、列表、文本 批量生成报告、合同
读取内容 提取文本、段落、表格 数据采集、内容解析
样式控制 字体、颜色、对齐、缩进 统一排版、规范输出
表格操作 创建、编辑、读取、追加行 成绩表、统计表、财务表
图片插入 本地图片、设置尺寸 报告配图、图表展示
文档修改 替换文本、追加内容 模板填充、信息更新
概念二：Word 文档结构（python-docx 视角）
  • Document：整个文档对象，所有操作的入口
  • Paragraph：段落，Word 中最小的文本单元
  • Run：文本块，一个段落中同一样式的连续文本
  • Table：表格，由行（Row）和单元格（Cell）组成
  • Section：页面配置，边距、方向、纸张大小

2.2 关键术语解释

⚠️ 注意：以下术语是看懂 python-docx 代码的基础，必须掌握。

  1. Paragraph（段落）：按回车键分隔的文本块，所有内容必属于段落
  2. Run（文本块）：同一格式的连续文字，一个段落可包含多个 Run
  3. Style（样式）：字体、字号、颜色、对齐方式等格式集合
  4. Cell（单元格）：表格最小单元，可存放文本、段落、图片

2.3 技术架构概览

💡 架构理解：

plaintext

复制代码 
┌─────────────────────────────────────────┐
│              文档入口 Document          │
│           docx.Document() 总入口        │
├─────────────────────────────────────────┤
│              内容层 Content             │
│        段落 Paragraph / 表格 Table      │
├─────────────────────────────────────────┤
│              文本层 Text                │
│           文本块 Run / 字体 Font        │
├─────────────────────────────────────────┤
│              样式层 Style               │
│        段落样式 / 字符样式 / 表格样式    │
└─────────────────────────────────────────┘

三、环境安装与快速入门

3.1 安装 python-docx

bash

运行

复制代码 
pip install python-docx
pip show python-docx

3.2 第一个程序：创建并保存 Word 文档

python

运行

python 复制代码 
# 导入核心类
from docx import Document

# 1. 创建空白文档对象
doc = Document()

# 2. 添加主标题（级别0~9）
doc.add_heading('python-docx 快速入门示例', level=0)

# 3. 添加普通段落
doc.add_paragraph('这是使用 python-docx 自动生成的第一段文字。')

# 4. 保存文档到本地
doc.save('我的第一个Word文档.docx')

print("✅ Word文档创建成功！")

四、写入操作：从零构建完整 Word

4.1 段落与文本写入

4.1.1 基础段落写入

python

运行

python 复制代码 
from docx import Document

doc = Document()
doc.add_heading('段落写入实战', level=1)

# 添加普通段落
p1 = doc.add_paragraph('这是第一个标准段落。')
p2 = doc.add_paragraph('这是第二个段落，用于演示多行内容。')

# 支持换行符 \n
doc.add_paragraph('第一行内容\n第二行内容\n第三行内容')

doc.save('段落写入示例.docx')
4.1.2 Run 文本块（精细化样式控制）

python

运行

python 复制代码 
from docx import Document

doc = Document()
# 创建空段落
p = doc.add_paragraph()

# 添加第一个文本块：加粗
run1 = p.add_run('加粗文字')
run1.bold = True

# 添加第二个文本块：普通
run2 = p.add_run('，普通文字，')

# 添加第三个文本块：斜体
run3 = p.add_run('斜体文字')
run3.italic = True

doc.save('Run文本块示例.docx')

4.2 标题与有序 / 无序列表

python

运行

python 复制代码 
from docx import Document

doc = Document()

# 多级标题
doc.add_heading('一级标题', level=1)
doc.add_heading('二级标题', level=2)
doc.add_heading('三级标题', level=3)

# 无序列表（圆点）
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.save('标题与列表示例.docx')

4.3 字体样式设置（字号、颜色、字体）

python

运行

python 复制代码 
from docx import Document
from docx.shared import Pt, RGBColor  # 字号、颜色
from docx.enum.text import WD_ALIGN_PARAGRAPH  # 对齐

doc = Document()
p = doc.add_paragraph()

# 设置文字内容
run = p.add_run('python-docx 字体样式完整版演示')
font = run.font

# 字体设置
font.name = '微软雅黑'        # 字体
font.size = Pt(16)            # 字号16磅
font.bold = True              # 加粗
font.italic = False           # 斜体关闭
font.color.rgb = RGBColor(0, 76, 153)  # 蓝色

# 段落居中
p.alignment = WD_ALIGN_PARAGRAPH.CENTER

doc.save('字体样式示例.docx')

4.4 段落格式：缩进、对齐、行距

python

运行

python 复制代码 
from docx import Document
from docx.shared import Pt, Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()
p = doc.add_paragraph('这是一段演示段落格式的文本，包含对齐、缩进、行距设置。')

# 1. 对齐方式：居中/左对齐/右对齐/两端对齐
p.alignment = WD_ALIGN_PARAGRAPH.CENTER

# 2. 首行缩进2字符
p.paragraph_format.first_line_indent = Cm(0.74)

# 3. 行距1.5倍
p.paragraph_format.line_spacing = 1.5

# 4. 段前间距、段后间距
p.paragraph_format.space_before = Pt(12)
p.paragraph_format.space_after = Pt(6)

doc.save('段落格式示例.docx')

五、读取操作：提取 Word 里的所有内容

5.1 读取全文本

python

运行

python 复制代码 
from docx import Document

# 打开已存在的文档
doc = Document('我的第一个Word文档.docx')

# 存储所有文本
text_list = []

# 遍历所有段落
for para in doc.paragraphs:
    text_list.append(para.text)

# 拼接输出
full_text = '\n'.join(text_list)
print("📄 文档全部内容：")
print(full_text)

5.2 按段落读取并输出样式

python

运行

python 复制代码 
from docx import Document

doc = Document('段落写入示例.docx')

# 遍历段落，输出文本与样式
for index, para in enumerate(doc.paragraphs):
    print(f"第{index+1}段：{para.text}")
    print(f"样式名称：{para.style.name}")
    print("-" * 40)

5.3 读取 Run 文本块信息

python

运行

python 复制代码 
from docx import Document

doc = Document('Run文本块示例.docx')

for para in doc.paragraphs:
    for run in para.runs:
        print(f"文本：{run.text}")
        print(f"是否加粗：{run.bold}")
        print(f"是否斜体：{run.italic}")
        print("---")

六、表格操作：最常用实战核心

6.1 创建表格并写入数据

python

运行

python 复制代码 
from docx import Document
from docx.shared import Cm

doc = Document()
doc.add_heading('学生成绩统计表', level=1)

# 创建3行4列的表格
table = doc.add_table(rows=3, cols=4)
# 设置表格为网格样式
table.style = 'Table Grid'

# 设置表头
header_cells = table.rows[0].cells
header_cells[0].text = '姓名'
header_cells[1].text = '语文'
header_cells[2].text = '数学'
header_cells[3].text = '英语'

# 第一行数据
row1 = table.rows[1].cells
row1[0].text = '张三'
row1[1].text = '90'
row1[2].text = '95'
row1[3].text = '88'

# 第二行数据
row2 = table.rows[2].cells
row2[0].text = '李四'
row2[1].text = '85'
row2[2].text = '92'
row2[3].text = '94'

doc.save('表格创建示例.docx')

6.2 动态追加行（批量数据必备）

python

运行

python 复制代码 
from docx import Document

doc = Document()
# 先创建只有表头的表格
table = doc.add_table(rows=1, cols=3)
table.style = 'Table Grid'

# 表头
hdr = table.rows[0].cells
hdr[0].text = 'ID'
hdr[1].text = '商品名称'
hdr[2].text = '价格'

# 待插入的数据
data = [
    ('1', '笔记本电脑', '5999元'),
    ('2', '无线鼠标', '199元'),
    ('3', '机械键盘', '399元'),
    ('4', '显示器', '1299元')
]

# 循环添加行
for item in data:
    new_row = table.add_row()
    new_row.cells[0].text = item[0]
    new_row.cells[1].text = item[1]
    new_row.cells[2].text = item[2]

doc.save('动态添加行示例.docx')

6.3 读取表格全部数据

python

运行

python 复制代码 
from docx import Document

doc = Document('表格创建示例.docx')

# 获取文档中第一个表格
table = doc.tables[0]

# 遍历读取
for row_idx, row in enumerate(table.rows):
    row_data = []
    for cell in row.cells:
        row_data.append(cell.text)
    print(f"第{row_idx+1}行：{row_data}")

七、图片插入与页面设置

7.1 插入本地图片

python

运行

python 复制代码 
from docx import Document
from docx.shared import Cm

doc = Document()
doc.add_heading('图片插入演示', level=1)

# 插入图片，设置宽度为12厘米
# 请替换为你本地真实图片路径
doc.add_picture('test.png', width=Cm(12))

doc.add_paragraph('上图为演示图片，已自动适配宽度。')
doc.save('图片插入示例.docx')

7.2 页面设置：边距、横向 / 纵向

python

运行

python 复制代码 
from docx import Document
from docx.shared import Cm
from docx.enum.section import WD_ORIENT

doc = Document()
# 获取第一个节
section = doc.sections[0]

# 设置页边距：上下左右2.5厘米
section.top_margin = Cm(2.5)
section.bottom_margin = Cm(2.5)
section.left_margin = Cm(2.5)
section.right_margin = Cm(2.5)

# 设置为横向
section.orientation = WD_ORIENT.LANDSCAPE

doc.add_paragraph('这是一个横向、边距统一的标准文档。')
doc.save('页面设置示例.docx')

八、修改现有文档

8.1 批量替换文本（模板填充神器）

python

运行

python 复制代码 
from docx import Document

def replace_word_text(doc, old_str, new_str):
    """
    替换文档中的指定文本（支持段落+表格）
    :param doc: Document对象
    :param old_str: 要替换的字符串
    :param new_str: 新字符串
    """
    # 替换段落中的文字
    for para in doc.paragraphs:
        if old_str in para.text:
            para.text = para.text.replace(old_str, new_str)
    
    # 替换表格中的文字
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                if old_str in cell.text:
                    cell.text = cell.text.replace(old_str, new_str)

# 使用示例
if __name__ == '__main__':
    # 打开模板文档
    doc = Document('合同模板.docx')
    # 批量替换变量
    replace_word_text(doc, '{{公司名称}}', '字节跳动科技有限公司')
    replace_word_text(doc, '{{签订日期}}', '2026年04月26日')
    replace_word_text(doc, '{{代表人}}', '张先生')
    # 保存新文档
    doc.save('合同_已填充.docx')

8.2 向现有文档追加内容

python

运行

python 复制代码 
from docx import Document

# 打开已存在的文档
doc = Document('我的第一个Word文档.docx')

# 追加标题
doc.add_heading('追加的二级标题', level=2)
# 追加段落
doc.add_paragraph('这是追加的新段落内容。')

doc.save('追加内容后文档.docx')

九、企业级实战：批量生成报告

python

运行

python 复制代码 
from docx import Document
from docx.shared import Pt

# 模拟批量数据
user_data = [
    {"name": "张三", "score": 92, "level": "优秀"},
    {"name": "李四", "score": 85, "level": "良好"},
    {"name": "王五", "score": 72, "level": "合格"},
    {"name": "赵六", "score": 61, "level": "合格"},
    {"name": "钱七", "score": 55, "level": "不合格"},
]

# 循环批量生成
for user in user_data:
    doc = Document()
    # 标题
    title = doc.add_heading(f'{user["name"]} 测评报告', 0)
    title.alignment = 1  # 居中
    
    # 内容
    doc.add_paragraph(f'姓名：{user["name"]}')
    doc.add_paragraph(f'综合得分：{user["score"]}')
    doc.add_paragraph(f'评级结果：{user["level"]}')
    
    # 保存
    doc.save(f'测评报告_{user["name"]}.docx')

print("✅ 批量生成报告完成！")

十、最佳实践分享

最佳实践一：样式优先

  • 先统一样式，再批量写入，避免逐字设置格式
  • 优先使用 Word 内置样式，兼容性最强
  • 复杂格式先在 Word 做好模板，再用 python 替换

最佳实践二：结构清晰

  • 标题层级严格使用 level=1~9
  • 段落、表格、图片分模块管理
  • 代码拆分为函数，便于复用

最佳实践三：稳定可靠

  • 捕获文件不存在、被占用等异常
  • 使用绝对路径避免找不到文件
  • 大批量写入时适当增加延时

最佳实践四：性能优化

  • 大表格用循环一次性添加，不频繁 add_row
  • 图片先压缩再插入
  • 缓存重复样式，避免重复创建

十一、常见问题解答

Q1：python-docx 不支持 .doc 格式？

A：不支持 。只支持 .docx（Word 2007 及以上）。可在 Word 中另存为 .docx 后再处理。

Q2：运行报错 "权限被拒绝"？

A：文件正被 Word 打开，关闭文档再运行代码即可。

Q3：中文显示乱码？

A：设置字体为微软雅黑、宋体、黑体等中文字体。

Q4：表格没有边框？

A：设置样式：table.style = 'Table Grid'

Q5：图片插入失败？

A：检查路径是否正确，支持格式：PNG/JPG/BMP。

十二、未来发展趋势

  1. AI + python-docx：AI 自动生成报告、智能排版
  2. 云端自动化：对接飞书 / 企业微信 / 钉钉自动发送
  3. 多格式互通：Word 与 PDF、Excel、Markdown 互转
  4. 低代码工具：可视化配置一键生成 Word

十三、本章小结

13.1 核心要点回顾

✅ 本章完整覆盖：

  1. 环境安装与入门示例
  2. 段落、标题、列表、字体、样式写入
  3. 文本、表格、Run 块读取
  4. 表格创建、读取、动态追加行
  5. 图片插入、页面边距 / 方向设置
  6. 文档修改、文本批量替换
  7. 企业级批量生成报告实战
  8. 最佳实践与高频问题解决

13.2 学习建议

  1. 先跑通所有示例代码，再修改参数练习
  2. 结合自己工作场景做实战（报表、合同、报告）
  3. 复杂排版优先使用模板 + 替换变量
  4. 遇到问题先看官方文档，再查常见问题

十四、课后练习

  1. 基础练习：创建一个包含标题、3 段文字、1 个表格的 Word 文档
  2. 进阶练习：读取任意 docx 文件，输出所有文本与表格内容
  3. 实战练习：批量生成 10 份带不同内容的个人简历 / 测评报告

十五、参考资料

  1. python-docx 官方文档：https://python-docx.readthedocs.io
  2. Python 官方文档：https://docs.python.org
  3. MSDN Office 开发文档：https://learn.microsoft.com

本文全套源码均已亲测可运行，注释超详细，零基础也能直接复制使用。专注分享 Python 办公自动化、数据分析、爬虫实战、模块精讲等硬核干货，拒绝水文、只讲落地！点赞 + 收藏 + 关注，下期继续分享更多能直接提升职场效率的 Python 神器，让你用代码解放双手，少加班、多赚钱！

相关推荐
yuanpan2 小时前
Python Pandas 库入门：介绍与基本使用教程
开发语言·python·pandas
m0_515098422 小时前
如何排查RAC节点被驱逐Eviction_CSS日志与宕机重启原因分析
jvm·数据库·python
gc_22992 小时前
学习C#调用OpenXml操作word文档的基本用法（26：学习文本运行类）
word·openxml·run
weixin_458580122 小时前
HTML函数工具是否适配HDR显示器_高动态范围指南【指南】
jvm·数据库·python
qq_654366982 小时前
Cgo 中正确设置 C 结构体内函数指针回调的完整方案
jvm·数据库·python
qq_432703662 小时前
如何处理复杂的SQL注入攻击_使用行为分析识别异常
jvm·数据库·python
sinat_383437362 小时前
如何在 Ubuntu Core（Snappy）上部署 Go Web 服务
jvm·数据库·python
pele2 小时前
怎么诊断MongoDB Config Server响应极慢的问题_高频Auto-split导致的元库写入压力
jvm·数据库·python
itzixiao2 小时前
L1-058 6翻了（15分）[java][python]
java·开发语言·python·算法
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026年AI前瞻：量子AI、具身智能与科学发现的新纪元052026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元06codex app每次打开重连5次Reconnecting问题解决07AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析082026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot09DeepSeek V4 全面解析：测评、对比、案例及实操指南102026 年 AI 辅助编程工具全景对比：Copilot、Cursor、Claude Code 与 Codex 深度解析