[诸神缄默不语-个人技术博文与视频目录](https://blog.csdn.net/PolarisRisingWar/article/details/116396744)

视频教程：[Python通过win32com库操作Word教程_哔哩哔哩_bilibili](https://www.bilibili.com/video/BV15pP6zeERt/)

如果需要原Jupyter notebook文件和用作示例的图片、文档，可以联系我。

[TOC]

# 引言

在 Python 生态中，操作 Word 文档的库有不少，比如 `python-docx` 主要处理 `.docx` 格式，而 `win32com`（即 `pywin32`）则提供了更为底层的控制能力——它直接调用微软 Office 的 COM 接口，这意味着**你的 Word 软件能做什么，`win32com` 就能做什么**。不仅可以读写文本，还能操作表格、图表、域代码、目录、格式转换，甚至执行查找替换等复杂任务。

不过，使用它也有一些前提和限制：

- **只能在 Windows 系统上运行**，并且必须已安装 Microsoft Word（WPS 或其他打开 Word 的软件不行）。
- 默认情况下，代码是单线程的。
- 操作完成后，**务必记得关闭 Word 客户端**（`doc.Close()` 和 `word.Quit()`），否则 Word 进程会一直留在后台，需要手动从任务管理器结束。

`win32com` 其实是一个通用 COM 客户端，不仅能操作 Word，还能操作 Excel、PPT、Outlook 等微软软件。本文只聚焦于 Word 的操作。

通过python-docx、docxtpl、Composer库处理Word文档的教程请参考：[Python处理Word文档完全指南：从基础到进阶](https://mp.weixin.qq.com/s/rQCMMu0FJVrKKzcyU-V3iQ)

# 安装

```bash
pip install pywin32
```

如果遇到常数（constants）加载异常（例如无法使用 `constants.wdReplaceAll`），可以尝试强制重新生成缓存：

```python
import win32com.client as win32
word = win32.gencache.EnsureDispatch('Word.Application')  # 替换win32.Dispatch()接口
```

或者手动删除缓存文件夹（通常在 `%temp%\gen_py` 下，例如 `C:\Users\用户名\AppData\Local\Temp\gen_py`）。

# 基础概念

在深入代码之前，先了解几个核心对象：

| 对象              | 说明                                             |
| ----------------- | ------------------------------------------------ |
| `Application`     | Word 应用程序本身，通过 `win32.Dispatch` 获得    |
| `Document`        | 代表一个打开的文档，通过 `Documents.Add` 或 `Documents.Open` 获取 |
| `Selection`       | 当前光标选中的区域（或光标位置）                 |
| `Range`           | 文档中的一个连续区域（可以不是选中状态）         |
| `Paragraph`       | 段落，由回车符分隔                               |
| `Font` / `ParagraphFormat` | 字体和段落格式                           |

# 1. 新建文档并写入文字

## 使用 Range 对象

```python
import win32com.client as win32

word = win32.Dispatch("Word.Application")
word.Visible = True   # True 会显示 Word 界面（但很快消失）

doc = word.Documents.Add()
range_obj = doc.Range(0, 0)
range_obj.InsertAfter("Hello World from Python!")

# 注意：必须使用绝对路径，否则会保存到 Word 的默认文件夹
doc.SaveAs(r"D:\your_path\test.docx")
doc.Close()
word.Quit()
```

## 使用 Selection 对象（模拟光标）

```python
word = win32.Dispatch("Word.Application")
word.Visible = False

doc = word.Documents.Add()
selection = word.Selection

selection.TypeText("Hello, World!")
selection.TypeParagraph()          # 换行（新段落）
selection.TypeText("这是第二行")

doc.SaveAs(r"D:\your_path\test.docx")
doc.Close()
word.Quit()
```

> **注意**：`Range` 是一个独立区域，不依赖光标；`Selection` 则代表当前光标位置，常用于模拟用户操作。

# 2. 打开文档，读取内容并追加文字

```python
word = win32.Dispatch("Word.Application")
word.Visible = False

doc = word.Documents.Open(r"D:\your_path\test.docx")

# 遍历所有段落打印内容
for paragraph in doc.Paragraphs:
    print(paragraph.Range.Text)

# 在文档末尾追加内容
doc.Content.InsertAfter("\n这是新增的内容")

doc.Close()
word.Quit()
```

> 注意：直接使用 `doc.Content.Text` 获取全文有时会返回异常结果（如只得到`这是第二行, World!`），所以推荐遍历段落。

# 3. 设置字体与段落格式

## 误区：使用 Selection 设置字体无效

```python
selection = word.Selection

# 字体设置无效
selection.Font.Name = "微软雅黑"
selection.Font.Size = 16
selection.Font.Bold = True
selection.Font.ColorIndex = 6      # 红色

# 段落设置有效
selection.ParagraphFormat.Alignment = 1   # 居中（0左 1中 2右 3两端）
selection.ParagraphFormat.LineSpacingRule = 0  # 单倍行距
```

原因：`Selection` 只是一个点，设置字体需要作用于一个区域。

## 正确方法：使用 Range 设置整个文档

```python
range_obj = doc.Content
range_obj.Font.Name = "微软雅黑"
range_obj.Font.Size = 16
range_obj.Font.Bold = True
range_obj.Font.ColorIndex = 6
range_obj.ParagraphFormat.Alignment = 1
range_obj.ParagraphFormat.LineSpacingRule = 0
```

## 设置标题样式

```python
range_obj = doc.Range(0, 0)
range_obj.Text = "第一章 概述"
range_obj.Style = doc.Styles("标题 1")   # 英文版可能是 "Heading 1"
```

# 4. 插入表格

```python
range_obj = doc.Content
range_obj.Collapse(0)          # 0 折叠到末尾，1 折叠到开头

table = doc.Tables.Add(range_obj, NumRows=3, NumColumns=3)

# 单元格索引从 1 开始
table.Cell(1,1).Range.Text = "姓名"
table.Cell(1,2).Range.Text = "年龄"
table.Cell(1,3).Range.Text = "结果"

table.Cell(2,1).Range.Text = "张三"
table.Cell(2,2).Range.Text = "25"
table.Cell(2,3).Range.Text = "合格"
```

# 5. 查找与替换

## 简单替换（全文匹配）

```python
find = word.Selection.Find
find.Text = "{{name}}"
find.Replacement.Text = "张三"
find.Execute(Replace=2)          # Replace=2 表示全部替换
```

## 处理缓存异常问题

缓存异常的显著表现是无法导入 `constants` ，同时查找和替换功能也会出现异常。可以显式设置所有参数来解决问题：

```python
WD_FIND_CONTINUE = 1   # 继续查找
WD_REPLACE_ALL = 2     # 全部替换

rng = doc.Content
for old, new in [("{{name}}", "张三"), ("{{date}}", "2026-02-26")]:
    rng.Find.Execute(
        old, False, False, False, False, False,
        True, WD_FIND_CONTINUE, False, new, WD_REPLACE_ALL
    )
    rng = doc.Content   # 重新获取 Range，避免被移动
```

# 6. 插入图片

```python
range_obj = doc.Content
range_obj.Collapse(0)   # 移动到末尾

doc.InlineShapes.AddPicture(
    r"D:\your_path\pic1.jpeg",
    False, True, range_obj
)
```

# 7. 更新目录

```python
for toc in doc.TablesOfContents:
    toc.Update()
```

# 8. Word 转 PDF 及 doc/docx 互转

```python
doc.ExportAsFixedFormat(
    OutputFileName=r"D:\your_path\test.pdf",
    ExportFormat=17      # 17 代表 PDF；16 代表 docx；0/1 代表 doc
)
```

> 笔者曾基于此功能开发过一个桌面工具，支持 Word/PDF 互转及 Excel 格式互转，详情参考：[如何用Python处理文件：Word导出PDF](https://blog.csdn.net/PolarisRisingWar/article/details/155127590) 和 [doc / docx互相转换](https://blog.csdn.net/PolarisRisingWar/article/details/155065899)。

# 9. 插入域代码：以日期域为例

```python
range_obj = doc.Content
range_obj.Collapse(0)

field = doc.Fields.Add(
    Range=range_obj,
    Type=31               # wdFieldDate
)

# 等价写法（插入空域，再指定代码）
# field = doc.Fields.Add(
#     Range=range_obj,
#     Type=constants.wdFieldEmpty,
#     Text="DATE  \\* MERGEFORMAT"
# )
```

# 10. 实例：将纯文本图标签替换为 SEQ 域

**原始文档**：包含“图 1”、“图 2”等纯文本  
**目标**：替换为域代码 `图 { SEQ 图 \* ARABIC }`，实现自动编号。

```python
word = win32.gencache.EnsureDispatch('Word.Application')
word.Visible = False
doc = word.Documents.Open(r"D:\your_path\instance1.docx")

search_range = doc.Range()
search_range.Find.Text = "图 [0-9]{1,}"
search_range.Find.Wrap = 0                 # wdFindStop，不循环
search_range.Find.MatchWildcards = True    # 通配符匹配

found = search_range.Find.Execute()
while found:
    insert_point = search_range.Duplicate   # 复制当前 Range
    insert_point.Delete()                    # 删除原文本
    insert_point.InsertAfter("图 ")           # 插入“图 ”
    insert_point.Collapse(Direction=0)        # 折叠到末尾

    # 插入 SEQ 域
    seq_code = 'SEQ 图 \\* ARABIC'
    doc.Fields.Add(insert_point, -1, seq_code, False)  # -1 代表 wdFieldEmpty

    search_range.Collapse(Direction=0)
    found = search_range.Find.Execute()

doc.Fields.Update()
doc.SaveAs(r"D:\your_path\test.docx")
doc.Close()
word.Quit()
```

# 11. 复杂实例：带章节号的图标签（如 图 1-1、图 1-2）

**原始文档**：包含“图 1-1”、“图 1-2”等纯文本  
**目标**：替换为 `图 { STYLEREF 1 \s }-{ SEQ 图 \* ARABIC \s 1 }`，其中章节号来自标题1（一级标题）的编号。

```python
word = win32.Dispatch("Word.Application")
word.Visible = False
doc = word.Documents.Open(r"D:\your_path\instance2.docx")

search_range = doc.Range()
search_range.Find.Text = "图 [0-9]{1,}-[0-9]{1,}"
search_range.Find.Wrap = constants.wdFindStop
search_range.Find.MatchWildcards = True

found = search_range.Find.Execute()
while found:
    insert_point = search_range.Duplicate
    insert_point.Delete()
    insert_point.InsertAfter("图 ")
    insert_point.Collapse(Direction=constants.wdCollapseEnd)

    # 插入 STYLEREF 域
    styleref_code = 'STYLEREF 1 \\s'
    field_styleref = doc.Fields.Add(insert_point, constants.wdFieldEmpty, styleref_code, False)
    field_styleref.Update()

    # 将光标移动到域之后
    field_styleref.Select()
    word.Selection.Collapse(Direction=constants.wdCollapseEnd)
    insert_point = word.Selection.Range.Duplicate

    # 插入连字符
    insert_point.InsertAfter("-")
    insert_point.Collapse(Direction=constants.wdCollapseEnd)

    # 插入 SEQ 域
    seq_code = 'SEQ 图 \\* ARABIC \\s 1'
    doc.Fields.Add(insert_point, constants.wdFieldEmpty, seq_code, False)

    search_range.Collapse(Direction=constants.wdCollapseEnd)
    found = search_range.Find.Execute()

doc.Fields.Update()
doc.SaveAs(r"D:\your_path\test.docx")
doc.Close()
word.Quit()
```

> 关键点：  
> - 使用 `Duplicate` 复制 Range，避免原对象被后续操作改变。  
> - 插入域后需要先更新域（`Update()`），然后选中它再折叠，才能准确定位到域之后的位置。  
> - 这些技巧在插入复杂域时非常重要。


# 总结

`win32com` 是操作 Word 的强大工具，几乎可以实现 VBA 能做的所有事情。本文涵盖了从新建文档、格式设置、表格、查找替换、图片、目录、格式转换到域代码操作等常见需求。虽然它有平台限制（仅 Windows + 已安装Word软件），但对于需要深度控制 Word 文档的自动化任务来说，它是不可或缺的利器。

视频教程：Python通过win32com库操作Word教程_哔哩哔哩_bilibili

Python通过win32com库操作Word教程

该教程介绍了Python中pywin32（调用win32com）库操作Word文档的方法，包含新建、写入、设置格式、插入表格、图片、查找替换、插入域代码等功能，还涉及Word转PDF及格式互转，最后通过实例展示了查找替换与插入域代码的应用。

程序开发工程师

编程语言

开发工具

后端

Python通过win32com库操作Word全教程，涵盖新建文档、格式设置、表格插入、查找替换、图片处理、目录更新、PDF转换及域代码操作。适用于Windows系统，需安装Office Word，提供从基础到高阶的自动化操作指南，附实例代码和资源文件。

Windows

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Python通过win32com库操作Word教程-腾讯云开发者社区-腾讯云

Python通过win32com库操作Word教程

Python通过win32com库操作Word教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐