python-docx 安装与快速入门

一、前言 📝

你所能搜索到的关于使用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'

三、更新ing