本文详解如何使用 apache poi 读取并填充现代 word 文档（.docx）中的文本框、复选框等表单域，明确指出旧版 .dot/.doc（97–2003）格式不被支持，并提供可运行的 java 示例与关键注意事项。
本文详解如何使用 apache poi 读取并填充现代 word 文档（.docx）中的文本框、复选框等表单域，明确指出旧版 .dot/.doc（97–2003）格式不被支持，并提供可运行的 java 示例与关键注意事项。
Apache POI 对 Word 文档的支持分为两个主要模块：HWPF（用于旧版二进制 .doc 格式）和 XWPF（用于基于 OOXML 的 .docx 格式）。需要特别强调的是：POI 的 HWPF 模块完全不支持读取或操作 Word 97–2007 模板（.dot）或文档（.doc）中的表单域（如 ActiveX 控件、Legacy Forms 字段）。这些字段在二进制格式中缺乏标准化结构，POI 未实现其解析逻辑，社区也无可靠补丁。因此，任何尝试用 HWPFDocument 处理 .dot 表单域的操作均会失败或静默忽略。
✅ 正确路径是迁移到 .docx 格式，并使用 XWPF 模块配合 Word 的 Content Controls（内容控件） —— 这是 Microsoft 推荐的现代表单构建方式（自 Word 2007 起支持），包括 Text Content Control、Checkbox Content Control 和 Dropdown List 等，且 POI 提供了稳定支持。
以下是一个完整示例，展示如何加载含内容控件的 .docx 模板、遍历并填充字段：
import org.apache.poi.xwpf.usermodel.*;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
public class DocxFormFiller {
public static void main(String[] args) throws IOException {
String templatePath = "template_with_controls.docx";
String outputPath = "filled_form.docx";
try (XWPFDocument doc = new XWPFDocument(new FileInputStream(templatePath))) {
// 遍历所有段落中的内容控件
for (XWPFParagraph para : doc.getParagraphs()) {
for (XWPFSDT sdt : para.getBodyElements()) {
if (sdt.getContent() instanceof XWPFRun) {
handleContentControl(sdt);
}
}
}
// 遍历表格单元格中的内容控件（常被忽略！）
for (XWPFTable table : doc.getTables()) {
for (XWPFTableRow row : table.getRows()) {
for (XWPFTableCell cell : row.getTableCells()) {
for (XWPFSDT sdt : cell.getBodyElements()) {
handleContentControl(sdt);
}
}
}
}
// 写出结果
try (FileOutputStream out = new FileOutputStream(outputPath)) {
doc.write(out);
}
System.out.println("✅ 表单已成功填充并保存至: " + outputPath);
}
}
private static void handleContentControl(XWPFSDT sdt) {
XWPFSDTContent content = sdt.getContent();
if (content == null) return;
// 填充文本内容控件（如“姓名”、“邮箱”）
if (sdt.getContent().getText().contains("<<NAME>>")) {
content.setText("张三");
} else if (sdt.getContent().getText().contains("<<EMAIL>>")) {
content.setText("zhangsan@example.com");
}
// 填充复选框内容控件（注意：需通过 XML 属性判断状态）
// 更健壮的方式：检查 sdt.getXmlObject().getSdtPr().getCheckBox()
if (sdt.getXmlObject().getSdtPr().getCheckBox() != null) {
boolean isChecked = "同意条款".equals(sdt.getContent().getText());
// 设置复选框状态：true → 选中（✓），false → 未选中（□）
sdt.getContent().setText(isChecked ? "✓" : "□");
}
}
}? 关键注意事项：
- ✅ 模板准备前提：务必在 Word 中使用「开发工具」选项卡 → 「设计模式」→ 插入「纯文本」或「复选框」内容控件（非旧版“表单域”或 ActiveX 控件）；
- ⚠️ 命名约定建议：为内容控件设置占位文本（如 <<FULL_NAME>>），便于代码精准匹配，避免硬编码索引；
- ⚠️ 复选框处理限制：POI 当前（v5.2.4+）尚不直接暴露 setChecked() 方法，需手动修改内部文本或 XML；生产环境推荐结合 XmlCursor 操作底层 w:sdt 结构；
- ? Maven 依赖（确保使用最新稳定版）：
<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.4</version> </dependency>
? 总结：放弃对 .dot/.doc 表单域的技术幻想，拥抱 .docx + Content Controls 是唯一可行、可维护、可测试的方案。通过 XWPFSDT 接口操作内容控件，不仅能实现动态填充，还天然支持国际化、样式保留与后续 PDF 导出等扩展场景。
