Word 文档文本查找与替换的 Java 实现方案

在文档处理工作中，批量修改文本内容是一项高频需求。无论是更正文档中反复出现的错误术语、更新合同模板中的占位信息，还是将特定文本替换为图片，通过编程方式实现查找与替换都能显著提升工作效率。本文将介绍如何利用 Java 语言，基于 Spire.Doc for Java 库实现 Word 文档中的文本查找与替换功能。

环境配置

本文示例所使用的库为 Spire.Doc for Java。若使用 Maven 管理项目依赖，可在 pom.xml 中添加以下配置：

xml 复制代码

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.cn/repository/maven-public/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.6.0</version>
    </dependency>
</dependencies>

对于不使用 Maven 的项目，可手动下载 JAR 文件并添加到项目的类路径中。

替换所有匹配文本

Document.replace() 方法是实现批量文本替换的核心 API。该方法默认替换文档中所有匹配的目标文本，并支持区分大小写和全字匹配两种查找模式。

参数说明：

第一个参数：要查找的文本
第二个参数：替换后的新文本
第三个参数：是否区分大小写（true 为区分）
第四个参数：是否全字匹配（true 为仅匹配完整单词）

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class ReplaceAllMatches {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("示例文档.docx");

        // 将文档中所有"旧术语"替换为"新术语"
        // 第三个参数false表示不区分大小写，第四个参数 true 表示全字匹配
        document.replace("旧术语", "新术语", false, true);

        document.saveToFile("替换结果.docx", FileFormat.Docx_2013);
        document.dispose();
    }
}

替换第一个匹配项

某些场景下，开发者只需替换文档中首次出现的特定文本。可通过 Document.setReplaceFirst(true) 方法将替换模式调整为仅处理第一个匹配项。

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class ReplaceFirstMatch {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("示例文档.docx");

        // 设置为仅替换第一个匹配项
        document.setReplaceFirst(true);

        document.replace("旧术语", "新术语", false, true);

        document.saveToFile("替换首个匹配项.docx", FileFormat.Docx_2013);
        document.dispose();
    }
}

批量替换多个词汇

当需要同时替换多个不同的关键词时，可使用 Map 存储替换规则，通过遍历逐一执行替换操作。

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import java.util.HashMap;
import java.util.Map;

public class ReplaceMultipleTerms {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("模板文档.docx");

        Map<String, String> replaceMap = new HashMap<>();
        replaceMap.put("#客户名称#", "张三科技有限公司");
        replaceMap.put("#联系人#", "李经理");
        replaceMap.put("#日期#", "2026年6月22日");

        for (Map.Entry<String, String> entry : replaceMap.entrySet()) {
            document.replace(entry.getKey(), entry.getValue(), true, true);
        }

        document.saveToFile("批量替换结果.docx", FileFormat.Docx_2013);
        document.dispose();
    }
}

该方法特别适用于基于模板批量生成合同、报告或通知等场景。

将文本替换为图片

Spire.Doc for Java 支持将文档中的文本占位符替换为图片。实现思路是先查找目标文本的所有匹配项，然后在每个匹配位置插入图片对象，最后删除原始文本。

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.documents.TextSelection;
import com.spire.doc.fields.DocPicture;
import com.spire.doc.fields.TextRange;

public class replaceTextWithImage {

    public static void main(String[] args) {

        // 创建 Document 类实例
        Document document = new Document();

        // 加载 Word 文档
        document.loadFromFile("Cave Art.docx");

        // 查找文档中所有匹配 "deer" 的字符串
        TextSelection[] selections = document.findAllString("deer", true, true);
        
        // 将所有匹配项替换为图片
        int index = 0;
        TextRange range = null;
        for (Object obj : selections) {

            TextSelection textSelection = (TextSelection)obj;
            
            // 创建 DocPicture 对象并加载图片
            DocPicture pic = new DocPicture(document);
            pic.loadImage("deer.png");
            
            range = textSelection.getAsOneRange();
            index = range.getOwnerParagraph().getChildObjects().indexOf(range);
            range.getOwnerParagraph().getChildObjects().insert(index, pic);
            range.getOwnerParagraph().getChildObjects().remove(range);
        }
        
        // 将特定匹配项替换为图片（注释部分）
        // 创建 DocPicture 对象并加载图片
        // DocPicture pic = new DocPicture(document);
        // pic.loadImage("deer.png");
        // Object object = selections[1];
        // TextSelection selection = (TextSelection) object;
        // TextRange textRange = selection.getAsOneRange();
        // int i = textRange.getOwnerParagraph().getChildObjects().indexOf(textRange);
        // textRange.getOwnerParagraph().getChildObjects().insert(i, pic);
        // textRange.getOwnerParagraph().getChildObjects().remove(textRange);

        // 保存文档
        document.saveToFile("ReplaceTextWithImage.docx", FileFormat.Docx_2013);
    }
}

应用场景与注意事项

合同与报告生成：通过批量替换占位符，可快速生成规范化文档
术语统一修正：批量更正文档中反复出现的错误用词或旧版术语
模板填充 ：结合 Map 规则，将模板中的标记替换为实际数据

查找精度 ：replace() 方法的第三个参数控制是否区分大小写，第四个参数控制是否全字匹配。在处理英文内容时，合理设置这两个参数可避免非预期的替换结果。

资源管理 ：操作完成后调用 dispose() 方法释放文档对象占用的资源，是规范的编码实践。

总结

本文介绍了基于 Java 语言在Word文档中实现文本查找与替换的技术方案。通过 Document.replace() 方法可快速完成全局文本替换，配合 setReplaceFirst(true) 可实现仅替换首次匹配项。对于多词汇批量更新，使用 Map 存储替换规则后遍历执行是高效的方式。此外，通过 findAllString() 定位匹配位置并结合图片插入与文本删除操作，可将文本占位符替换为图片。这些方法在合同生成、报告制作和文档批量更新等场景中具有实用价值，能够帮助开发者以编程方式高效完成文档内容的批量修改任务。