使用 Python 查找和替换 Word 文档中的文本

在 Word 文档的自动化处理中，查找和替换文本是最基础也最频繁的操作之一。无论是批量修改合同中的条款编号、更新报告中的日期信息，还是在大量文档中统一调整术语表述，高效的文本查找替换能力都是文档处理流程的核心环节。本文将介绍如何使用 Python 在 Word 文档中实现文本的查找与替换，涵盖普通文本替换、正则表达式匹配替换以及查找后高亮显示等实用场景。

为什么通过编程实现查找替换

手动在 Word 中使用查找替换功能虽然方便，但在以下场景中，编程方式具有不可替代的优势：

批量处理：一次性对数十份文档执行相同的替换操作
复杂匹配：使用正则表达式匹配具有特定模式的文本，如编号、日期、邮箱地址等
精确控制：区分大小写、全词匹配等精细化替换策略
流程集成：将替换操作嵌入到更大的文档处理管道中，如合同模板生成、报告自动化等

环境搭建

在开始之前，需要安装支持 Word 文档操作的 Python 库。

bash 复制代码

pip install Spire.Doc

安装完成后，在脚本中导入相关模块即可开始使用。

基础文本替换

最基本的替换操作是将文档中的指定文本替换为新的内容。Replace() 方法接受四个参数：要查找的文本、替换后的文本、是否忽略大小写、是否全词匹配。

python 复制代码

from spire.doc import *
from spire.doc.common import *

inputFile = "Sample.docx"
outputFile = "ReplaceText.docx"

# 创建文档对象
document = Document()

# 从磁盘加载 Word 文件
document.LoadFromFile(inputFile)

# 将文档中的 "word" 替换为 "ReplacedText"
# 参数：查找文本, 替换文本, 忽略大小写, 全词匹配
document.Replace("word", "ReplacedText", False, True)

# 保存文档
document.SaveToFile(outputFile, FileFormat.Docx)
document.Close()

Replace() 方法的第二和第三个布尔参数决定了匹配的严格程度。False 表示区分大小写，True 作为第四个参数表示只匹配完整的单词而非单词的一部分。这种设计使得替换操作可以精确控制匹配范围，避免误替换。

使用正则表达式进行替换

当需要匹配的文本具有某种模式而非固定字符串时，正则表达式就派上了用场。例如，替换所有以 # 开头的标识符、匹配特定格式的日期或编号等。

python 复制代码

from spire.doc import *
from spire.doc.common import *
import re

inputFile = "Sample.docx"
outputFile = "ReplaceByRegex.docx"

# 创建文档对象
document = Document()

# 从磁盘加载 Word 文件
document.LoadFromFile(inputFile)

# 创建正则表达式，匹配以 # 开头的单词
regex = re.compile(r"#\w+\b")

# 使用正则表达式替换匹配的文本
document.Replace(regex, "Spire.Doc")

# 保存文档
document.SaveToFile(outputFile, FileFormat.Docx)
document.Close()

这里使用 Python 标准库 re 的 compile() 方法创建正则表达式对象，然后将其传递给 document.Replace() 方法。所有匹配该模式的文本都将被统一替换为目标字符串。这种方式特别适合处理具有规律性模式的文本内容，例如：

替换所有形如 #TAG001 的标签编号
将文档中所有邮箱地址替换为 [REDACTED]
统一调整日期格式，如将 YYYY/MM/DD 替换为 YYYY-MM-DD

查找文本并高亮显示

有时不需要替换文本内容，而是需要定位所有匹配的文本并进行视觉标记。这在文档审核、关键词检索结果标记等场景中非常实用。

python 复制代码

from spire.doc import *
from spire.doc.common import *

inputFile = "Sample.docx"
outputFile = "FindAndHighlight.docx"

# 创建文档对象
document = Document()

# 从磁盘加载 Word 文件
document.LoadFromFile(inputFile)

# 查找所有匹配的文本
textSelections = document.FindAllString("word", False, True)

# 遍历匹配结果，设置高亮颜色
for selection in textSelections:
    selection.GetAsOneRange().CharacterFormat.HighlightColor = Color.get_Yellow()

# 保存文档
document.SaveToFile(outputFile, FileFormat.Docx)
document.Close()

FindAllString() 方法返回一个文本选择集合，每个元素代表文档中一处匹配位置。通过 GetAsOneRange() 获取对应的文本范围，然后访问 CharacterFormat.HighlightColor 属性设置高亮颜色。参数 False 表示区分大小写，True 表示全词匹配。

查找并替换为图片

除了替换为文本，还可以将查找到的文本替换为图片。这在批量插入 Logo、签名或产品图片等场景中非常实用。

python 复制代码

from spire.doc import *
from spire.doc.common import *

inputFile = "Sample.docx"
outputFile = "ReplaceWithImage.docx"

# 创建文档对象
document = Document()

# 从磁盘加载 Word 文件
document.LoadFromFile(inputFile)

# 创建图片对象
image = DocPicture(document)
image.LoadImage("logo.png")

# 查找所有 "[LOGO]" 占位符
textSelections = document.FindAllString("[LOGO]", False, False)

# 将每个匹配位置替换为图片
for selection in textSelections:
    range = selection.GetAsOneRange()
    # 清除原文本
    range.Text = ""
    # 在原文本位置插入图片
    range.ChildObjects.Add(image.Clone())

# 保存文档
document.SaveToFile(outputFile, FileFormat.Docx)
document.Close()

这种方式常用于模板文档处理：在文档中放置占位符（如 [LOGO]、[SIGNATURE]），然后通过代码批量替换为实际图片。

批量处理多个文档

在实际工作中，经常需要对目录下的多个 Word 文件执行相同的查找替换操作。结合 Python 的文件遍历能力，可以实现高效的批量处理。

python 复制代码

import os
from spire.doc import *
from spire.doc.common import *

input_dir = "./documents"
output_dir = "./processed"

os.makedirs(output_dir, exist_ok=True)

# 遍历目录中的所有 .docx 文件
for filename in os.listdir(input_dir):
    if filename.endswith(".docx"):
        input_path = os.path.join(input_dir, filename)
        output_path = os.path.join(output_dir, filename)

        document = Document()
        document.LoadFromFile(input_path)

        # 执行替换操作
        document.Replace("旧公司名称", "新公司名称", False, True)

        document.SaveToFile(output_path, FileFormat.Docx)
        document.Close()

        print(f"已处理: {filename}")

这段代码遍历指定目录下的所有 .docx 文件，对每份文档执行相同的文本替换，并将结果保存到输出目录。这种模式在企业更名、术语统一、模板更新等场景中非常实用。

实用技巧

使用替换回调进行精细控制

对于需要更复杂逻辑的替换场景，可以在替换前检查匹配内容的上下文，决定是否执行替换：

python 复制代码

# 先查找所有匹配项
textSelections = document.FindAllString("Python", False, True)

# 根据上下文决定是否替换
for selection in textSelections:
    range = selection.GetAsOneRange()
    # 仅在段落样式为标题时替换
    if range.OwnerParagraph.StyleName.startswith("Heading"):
        range.Text = "Python Programming"

处理替换后的格式保留

替换文本时，原有的字符格式（字体、颜色、大小等）默认会保留。如果需要同时修改格式，可以在替换后重新设置：

python 复制代码

textSelections = document.FindAllString("old term", False, True)
for selection in textSelections:
    range = selection.GetAsOneRange()
    range.Text = "new term"
    range.CharacterFormat.Bold = True
    range.CharacterFormat.TextColor = Color.get_Blue()

总结

本文介绍了使用 Python 在 Word 文档中查找和替换文本的多种方法，包括基础文本替换、正则表达式匹配替换、查找后高亮显示、替换为图片以及批量文件处理。这些操作覆盖了从简单文本修改到复杂模式匹配的主要场景。

核心 API 围绕 Replace() 和 FindAllString() 两个方法展开。前者用于直接替换，支持普通字符串和正则表达式两种匹配模式；后者用于定位匹配位置，配合格式设置实现高亮标记等效果。掌握这些基础操作后，可以进一步结合 Python 的文件处理能力，构建高效的文档批量处理工作流。