一、前言 📝

你所能搜索到的关于使用Python处理Word文档的教程几乎或多或少都有python-docx的身影，可以说，若你预期编写自动化word生成程序必然会涉及到这一模块；

然而在大多数情况下我并不建议任何人通过通读技术文档或者阅读本文这类技术博客来达成编写一个简单处理脚本的目的——日益智能化的大模型 🤖 轻轻松松抵得过你数小时的苦学甚至数年乃至数十年，更何况python-docx并不是一个语法有多复杂的模块，甚至一个具有一定word操作基础的编程小白 🐣 理解起来也并不困难。

本系列博客仅面向一类情况：当你的大模型编写出的程序不能达到你的预期/较为复杂的任务要求，导致你不得不亲自出手时——

忽略以上长难句，本系列我会尽量约束在文字最少的情况下使你花费最少的时间 ⏱️ 了解这一模块。

1.核心注意事项

python-docx 新旧版本API不兼容

2.安装

pip install python-docx

3.官方地址

python-docx官方文档地址

二、快速开始

1. 打开/创建文档

• 创建空白文档（基于默认模板）：

  from docx import Document
  document = Document()  # 类似新建空白Word文档
  

• （扩展提示）若需编辑现有文档，可传入文档路径：Document("existing_doc.docx")

2. 添加段落

段落是 Word 文档的基础元素，支持直接添加或插入到指定位置：

• 末尾添加段落：

  document.add_paragraph('普通段落内容') 
  

• 在指定段落前插入新段落：

  existing_paragraph = document.add_paragraph('已有段落') # 保留了引用，方便后续结构调整，若结构是确定的不必保存
  existing_paragraph.insert_paragraph_before('插入到已有段落上方的内容')
  

3. 添加标题

支持 0-9 级标题，满足文档层级划分需求：

• 指定层级（2 级标题：与word中概念一致）：

  document.add_heading('子章节标题', level=2)  # 参数缺省时默认 level=1
  

• 标题级为 0 时生成“Title”样式段落，实际上就是文档大标题（非单独标题页）。

4. 添加分页符

强制后续内容换行到新页面：

document.add_page_break()

提示：频繁使用分页符时，可通过设置段落样式（如指定级别标题自动分页）优化代码。

5. 添加表格

支持固定行数/列数创建，满足数据展示需求：

• 基础创建与单元格赋值：

  table = document.add_table(rows=2, cols=2) # 创建2行2列表格
  table.cell(0, 1).text = '第一行第二列内容'   # 通过索引访问单元格并设置内容，与列表索引机制相同
  

• 表格样式与属性：
  • 应用内置样式（需移除样式名中的空格）：table.style = 'LightShading-Accent1'
  • 统计行数/列数：len(table.rows)、len(table.columns)

6. 添加图片

支持本地文件或文件对象，可自定义尺寸以保持比例：

• 基础插入：

  document.add_picture('image.png')  # 按原生尺寸插入
  

• 自定义尺寸（推荐只指定宽度/高度，自动保持纵横比）：

  from docx.shared import Inches, Cm
  document.add_picture('image.png', width=Inches(1.0))   # 按英寸设置宽度（高度自动缩放）
  document.add_picture('image.png', height=Cm(5.0))   # 按厘米设置高度
  

7. 应用段落样式

类似 CSS 样式，可一次性设置段落的整体格式：

• 创建段落时直接指定样式：

  document.add_paragraph('项目符号列表项', style='ListBullet')
  

• 或后续修改样式：

  paragraph = document.add_paragraph('普通段落')
  paragraph.style = 'List Bullet'  # 样式名与Word UI一致
  

8. 设置字符格式（粗体/斜体）

字符格式需通过“Run”对象操作（一个段落可包含多个 Run）：

paragraph = document.add_paragraph('普通文本 ') # 创建段落并拆分Run
paragraph.add_run('加粗内容').bold = True # 加粗文本
paragraph.add_run(' 斜体内容').italic = True # 斜体文本

注意：Run 之间的空格需手动添加，否则会无缝拼接，当然对于中文来说大部分情况下不需要注意这一点。

9. 应用字符样式

专门用于设置字符级格式（如字体、颜色等）：

• 添加 Run 时指定样式：

  paragraph = document.add_paragraph('普通文本，')
  paragraph.add_run('带强调样式的文本', 'Emphasis')
  

• 后续修改字符样式：

  run = paragraph.add_run('后续修改样式的文本')
  run.style = 'Emphasis'
  

三、常见问题

1. 中文字体设置无效

python-docx 高层 API（如 run.font.name = '仿宋_GB2312'）在处理中/英文混排时，可能出现中文字体设置无效，仍然为默认字体的问题，所以需要直接操作 Word 文档的底层 XML 结构来彻底统一字体。

• Word 的 XML 结构：.docx 文件本质是压缩的 XML 文档，文本的字体样式存储在 <w:rPr>（运行属性，run properties）节点下的 <w:rFonts>（字体集合）节点中；
• run 的含义：run 是 Word 中「最小文本格式单元」—— 一段连续、相同格式的文本就是一个 run（比如同一段中“加粗文字”和“普通文字”是两个不同 run）；
• qn() 函数的作用：是 python-docx 提供的「XML 命名空间辅助函数」，用于生成带命名空间的 XML 标签（比如 qn('w:rFonts') 会生成 {http://schemas.openxmlformats.org/wordprocessingml/2006/main}rFonts），避免 XML 标签冲突。

# 1. 获取或创建当前 run 的「运行属性节点」（<w:rPr>）
rPr = run._element.get_or_add_rPr()

• run._element：获取 run 对应的底层 XML 元素（python-docx 高层对象的底层封装）；
• get_or_add_rPr()：如果该 run 已有 <w:rPr> 节点（已设置过字体、字号等样式），则直接获取；如果没有，则新建一个 <w:rPr> 节点（确保后续能添加字体配置）；
• rPr：最终拿到的「运行属性节点」，所有文本样式（字体、颜色、加粗等）都存在这里。

# 2. 在 <w:rPr> 中查找「字体集合节点」（<w:rFonts>）
rFonts = rPr.find(qn('w:rFonts'))

• rPr.find(...)：在 <w:rPr> 节点下搜索 <w:rFonts> 节点（该节点专门存储字体配置）；
• 若该 run 之前没设置过字体，rFonts 会返回 None。

# 3. 如果没找到 <w:rFonts> 节点，就新建一个并添加到 <w:rPr> 中
if rFonts is None:
    rFonts = OxmlElement('w:rFonts')  # 新建 <w:rFonts> 节点
    rPr.append(rFonts)  # 将新建的节点挂载到 <w:rPr> 下（使其生效）

• OxmlElement('w:rFonts')：创建纯 XML 格式的 <w:rFonts> 节点（python-docx 底层 XML 操作类）；
• 必须将新建节点 append 到 rPr 中，否则配置不会被 Word 识别。

# 4. 设置中文字体（eastAsia 对应 Word 的「东亚字体」，专门用于中文）
rFonts.set(qn('w:eastAsia'), '仿宋_GB2312')

• rFonts.set(name, value)：给 <w:rFonts> 节点添加属性；
• qn('w:eastAsia')：对应 XML 属性 w:eastAsia，专门指定「东亚文字（中文、日文、韩文等）」的字体；
• '仿宋_GB2312'：公文标准中文宋体，必须是系统已安装的字体（Windows 自带，Mac/Linux 需手动安装）。

# 5. 设置 ASCII 字体（专门用于英文、数字、标点符号）
rFonts.set(qn('w:ascii'), '仿宋_GB2312')

• w:ascii：对应 XML 属性，指定「ASCII 字符（a-z、A-Z、0-9、英文标点）」的字体；
• 这里强制设为「仿宋_GB2312」，避免英文/数字默认用 Calibri 等字体，确保格式统一。

# 6. 设置高 ASCII 字体（用于特殊符号、扩展 ASCII 字符，如 €、§ 等）
rFonts.set(qn('w:hAnsi'), '仿宋_GB2312')

• w:hAnsi：对应 XML 属性，指定「高 ASCII 字符（扩展字符集，如特殊符号、非英文字母）」的字体；
• 补充设置该属性，确保文档中所有字符（包括特殊符号）都统一为仿宋_GB2312。