Java 操作 Word 文档的常用功能实践

在 Java 后端开发中，与 Word 文档打交道是一项绕不开的需求。无论是生成业务报告、导出合同模板、还是处理用户上传的文档内容，都需要一套稳定可用的文档处理方案。本文记录几种常见的 Word 编辑操作，供有类似需求的开发者参考。

环境配置

在 Maven 项目中，需要在 pom.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>13.9.19</version>
    </dependency>
</dependencies>

如果不使用 Maven，也可以手动下载 JAR 包并添加到项目的 ClassPath 中。该库提供免费版本，使用时需注意其限制条件：加载或保存 Word 文档时，不超过 500 个段落和 25 个表格；转换为 PDF 等格式时仅支持前 3 页内容 。实际项目中需根据业务文档的规模评估是否满足需求。

此外，该组件无需安装 Microsoft Office 环境即可独立运行，对于部署在服务端的应用程序而言较为便利 。

功能一：文本查找与替换

文本替换是 Word 编辑中最基础的操作之一，常用于动态填充模板中的占位符。通过 replace 方法可以定位文档中的指定文本并一次性替换所有匹配项。如果只需要替换第一个匹配项，可先调用 setReplaceFirst(true) 设置替换模式。

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

public class TextReplaceExample {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("template.docx");
        
        // 定义替换映射
        Map<String, String> replaceMap = new HashMap<>();
        replaceMap.put("#name#", "张三");
        replaceMap.put("#date#", "2026年4月13日");
        replaceMap.put("#amount#", "¥12,800");
        
        // 执行替换
        for (Map.Entry<String, String> entry : replaceMap.entrySet()) {
            document.replace(entry.getKey(), entry.getValue(), true, true);
        }
        
        document.saveToFile("output.docx", FileFormat.Docx);
        document.dispose();
    }
}

replace 方法的第三、第四个参数分别表示是否区分大小写和是否全字匹配，可根据实际需要调整。如果模板中的占位符采用 ${变量名} 的格式，也可以结合正则表达式 findAllPattern 进行更灵活的匹配 。

功能二：基于书签修改内容

书签是 Word 中一种实用的定位标记，特别适合在结构复杂的文档中精准替换内容。相比文本占位符，书签能够精确定位，且替换后不会丢失书签本身，便于后续再次更新 。

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

public class BookmarkExample {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("contract_template.docx");
        
        // 书签名与替换内容的映射
        Map<String, String> bookmarkData = new HashMap<>();
        bookmarkData.put("party_a", "XX科技有限公司");
        bookmarkData.put("party_b", "YY贸易有限公司");
        bookmarkData.put("contract_date", "2026年4月13日");
        bookmarkData.put("contract_amount", "人民币伍拾万元整（¥500,000）");
        
        BookmarksNavigator navigator = new BookmarksNavigator(document);
        for (Map.Entry<String, String> entry : bookmarkData.entrySet()) {
            navigator.moveToBookmark(entry.getKey());
            navigator.replaceBookmarkContent(entry.getValue(), true);
        }
        
        document.saveToFile("contract_output.docx", FileFormat.Docx);
        document.dispose();
    }
}

书签方式适用于合同、证书等需要保留结构并在多处精准插入内容的场景 。

功能三：添加批注

在团队协作或文档审阅场景中，批注功能用于对特定内容提出修改建议或补充说明。Spire.Doc 支持在指定文本或段落上添加批注 ：

import com.spire.doc.*;
import com.spire.doc.documents.*;
import com.spire.doc.fields.Comment;
import com.spire.doc.fields.TextRange;

public class AddCommentExample {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("report.docx");
        
        // 查找要批注的文本
        TextSelection find = document.findString("目标内容", false, true);
        TextRange range = find.getAsOneRange();
        Paragraph para = range.getOwnerParagraph();
        
        // 创建批注对象
        Comment comment = new Comment(document);
        comment.getBody().addParagraph().setText("此处建议补充数据来源说明。");
        comment.getFormat().setAuthor("审核人");
        
        // 将批注添加到段落并设置标记范围
        para.getChildObjects().add(comment);
        CommentMark startMark = new CommentMark(document, 
                comment.getFormat().getCommentId(), CommentMarkType.Comment_Start);
        CommentMark endMark = new CommentMark(document, 
                comment.getFormat().getCommentId(), CommentMarkType.Comment_End);
        
        int index = para.getChildObjects().indexOf(range);
        para.getChildObjects().insert(index, startMark);
        para.getChildObjects().insert(index + 2, endMark);
        
        document.saveToFile("report_with_comment.docx", FileFormat.Docx);
        document.dispose();
    }
}

如果需要对整个段落添加批注，可以使用更简洁的 Paragraph.appendComment() 方法 。

功能四：文档格式转换

Word 文档与其他格式之间的互转是日常开发中的高频需求。Spire.Doc 支持多种格式的双向转换 ：

Word 转 PDF

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

public class WordToPdf {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("report.docx");
        document.saveToFile("report.pdf", FileFormat.PDF);
        document.dispose();
    }
}

Word 与 TXT 互转

// Word 转 TXT
Document doc = new Document();
doc.loadFromFile("document.docx");
doc.saveToFile("document.txt", FileFormat.Txt);

// TXT 转 Word
Document txtDoc = new Document();
txtDoc.loadFromFile("notes.txt");
txtDoc.saveToFile("notes.docx", FileFormat.Docx);

Word 与 HTML 互转

import com.spire.doc.documents.XHTMLValidationType;

// Word 转 HTML
Document doc = new Document();
doc.loadFromFile("article.docx");
doc.saveToFile("article.html", FileFormat.Html);

// HTML 转 Word
Document htmlDoc = new Document();
htmlDoc.loadFromFile("content.html", FileFormat.Html, XHTMLValidationType.None);
htmlDoc.saveToFile("content.docx", FileFormat.Docx);

功能五：文档加密与保护

对于涉及敏感信息的文档，可以通过加密来限制访问权限 ：

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

public class DocumentProtection {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("confidential.docx");
        
        // 设置打开密码
        document.encrypt("open_password");
        
        // 设置编辑限制密码（仅允许填写表单域）
        document.protect(ProtectionType.Allow_Only_Form_Fields, "edit_password");
        
        document.saveToFile("protected.docx", FileFormat.Docx);
        document.dispose();
    }
}

读取加密文档时，在 loadFromFile 方法中传入密码即可：

Document document = new Document();
document.loadFromFile("protected.docx", FileFormat.Docx, "open_password");

两种模板处理方式的对比

在动态生成文档的场景中，文本替换和书签替换是两种常用方式，各有适用场景 ：

对比维度	文本占位符替换	书签替换
实现复杂度	简单，仅需定义占位符格式	稍复杂，需预先在模板中插入书签
定位精度	可能误替换正文中的相同文本	精准定位，不会误操作
可重复编辑	替换后占位符消失	替换后书签仍保留
图片插入	需单独处理图片替换逻辑	可配合其他 API 实现
适用场景	简单报告、信函等轻量模板	结构复杂的合同、证书等

选择哪种方式，取决于模板的复杂程度以及是否需要后续再编辑。

注意事项

在实际使用过程中，有几个问题值得关注：

1. 免费版限制：免费版本对文档规模有明确限制（500 段落、25 表格，PDF 转换仅前 3 页）。若业务文档较大，需确认是否在限制范围内 。

2. 字体兼容性：当文档中使用特殊字体时，目标环境中需安装对应字体，否则可能出现显示异常。建议优先使用通用字体族。

3. 资源释放：处理批量文档时，应在每次操作完成后调用 dispose() 方法释放资源 。

4. 模板设计建议：如果采用模板方式生成文档，建议使用明确的占位符格式（如 #变量名# 或 ${变量名}），避免占位符与文档正文内容混淆 。

小结

本文介绍了在 Java 中操作 Word 文档的几种常见功能，包括文本替换、书签操作、批注添加、格式转换以及文档保护。这些功能基本覆盖了日常开发中的主要 Word 处理场景。

在技术选型时，建议结合具体业务需求中的文档规模、格式复杂度以及部署环境约束综合评估，选择最契合项目实际的技术方案。