用 Java 操作 Word 文档？试试添加内容控件

在日常开发中，我们偶尔会遇到需要动态生成 Word 文档的需求，比如生成合同、报告或表单。除了普通的文本和图片，有时候我们还需要在文档里嵌入"可交互"的区域，比如下拉选项、日期选择器、复选框等。在 Word 里，这些功能被称为内容控件。

这篇文章就来聊一聊，在 Java 环境下如何向 Word 文档中添加内容控件。

什么是内容控件

内容控件是 Word 文档中一种可以限制或引导用户输入的结构化区域。常见的类型包括：

纯文本控件
格式文本控件
下拉列表控件
组合框控件
日期选择器
复选框

它们通常用于制作可填写的表单模板，或者用于文档自动化流程中。

环境准备

本文的代码示例基于 Spire.Doc for Java 实现，这是一个处理 Word 文档的 Java 库。

添加依赖

如果使用 Maven，可以在 pom.xml 中配置仓库和依赖：

xml 复制代码

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <url>https://repo.e-iceblue.com/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.4.9</version>
    </dependency>
</dependencies>

如果不使用 Maven，也可以直接下载 JAR 文件并手动引入到项目中。

导入相关类

代码中需要导入以下命名空间：

java 复制代码

import com.spire.doc.*;
import com.spire.doc.documents.*;
import com.spire.doc.fields.*;
import com.spire.doc.fields.checkbox.*;
import com.spire.doc.fields.dropdown.*;
import com.spire.doc.fields.date.*;

创建文档并添加内容控件

下面通过一段完整的示例，演示如何创建一个新 Word 文档，并依次添加多种内容控件。

初始化文档

java 复制代码

Document document = new Document();
Section section = document.addSection();

添加纯文本控件

纯文本控件允许用户输入单行或多行文本。

java 复制代码

Paragraph paragraph = section.addParagraph();
paragraph.appendText("姓名：");

StructureDocumentTag plainTextSDT = new StructureDocumentTag(document, SDTType.RichText);
paragraph.getItems().add(plainTextSDT);

添加下拉列表控件

下拉列表可以让用户从一组预设选项中进行选择。

java 复制代码

Paragraph paraDropDown = section.addParagraph();
paraDropDown.appendText("部门：");

StructureDocumentTag dropDownSDT = new StructureDocumentTag(document, SDTType.DropDownList);
DropDownList dropDown = new DropDownList(dropDownSDT);
dropDown.getListItems().add(new DropDownItem("技术部"));
dropDown.getListItems().add(new DropDownItem("市场部"));
dropDown.getListItems().add(new DropDownItem("销售部"));
dropDown.getListItems().add(new DropDownItem("人力资源部"));
dropDownSDT.getSDTProperties().setDropDownList(dropDown);

paraDropDown.getItems().add(dropDownSDT);

添加日期选择器

日期选择器可以方便用户选择日期。

java 复制代码

Paragraph paraDate = section.addParagraph();
paraDate.appendText("入职日期：");

StructureDocumentTag dateSDT = new StructureDocumentTag(document, SDTType.DatePicker);
Calendar cal = Calendar.getInstance();
cal.set(2024, Calendar.JANUARY, 1);
dateSDT.getSDTProperties().setCalendarType(CalendarType.Gregorian);
dateSDT.getSDTProperties().setFullDate(cal.getTime());

paraDate.getItems().add(dateSDT);

添加复选框

复选框适用于表示"是/否"或"同意/不同意"这类二元选择。

java 复制代码

Paragraph paraCheckBox = section.addParagraph();
paraCheckBox.appendText("是否在职：");

StructureDocumentTag checkBoxSDT = new StructureDocumentTag(document, SDTType.CheckBox);
CheckBox checkBox = new CheckBox();
checkBox.setChecked(false);
checkBoxSDT.getSDTProperties().setCheckBox(checkBox);

paraCheckBox.getItems().add(checkBoxSDT);

保存文档

java 复制代码

document.saveToFile("ContentControls.docx", FileFormat.Docx);
document.close();

完整示例代码

将上述步骤整合起来，得到一个完整的可运行示例：

java 复制代码

import com.spire.doc.*;
import com.spire.doc.documents.*;
import com.spire.doc.fields.dropdown.*;
import com.spire.doc.fields.checkbox.*;
import java.util.Calendar;

public class AddContentControls {
    public static void main(String[] args) {
        Document document = new Document();
        Section section = document.addSection();

        // 纯文本控件
        Paragraph p1 = section.addParagraph();
        p1.appendText("姓名：");
        StructureDocumentTag textSDT = new StructureDocumentTag(document, SDTType.RichText);
        p1.getItems().add(textSDT);

        // 下拉列表控件
        Paragraph p2 = section.addParagraph();
        p2.appendText("部门：");
        StructureDocumentTag dropDownSDT = new StructureDocumentTag(document, SDTType.DropDownList);
        DropDownList dropDown = new DropDownList(dropDownSDT);
        dropDown.getListItems().add(new DropDownItem("技术部"));
        dropDown.getListItems().add(new DropDownItem("市场部"));
        dropDownSDT.getSDTProperties().setDropDownList(dropDown);
        p2.getItems().add(dropDownSDT);

        // 日期选择器
        Paragraph p3 = section.addParagraph();
        p3.appendText("入职日期：");
        StructureDocumentTag dateSDT = new StructureDocumentTag(document, SDTType.DatePicker);
        Calendar cal = Calendar.getInstance();
        cal.set(2024, Calendar.JANUARY, 1);
        dateSDT.getSDTProperties().setFullDate(cal.getTime());
        p3.getItems().add(dateSDT);

        // 复选框
        Paragraph p4 = section.addParagraph();
        p4.appendText("是否在职：");
        StructureDocumentTag checkBoxSDT = new StructureDocumentTag(document, SDTType.CheckBox);
        CheckBox checkBox = new CheckBox();
        checkBox.setChecked(false);
        checkBoxSDT.getSDTProperties().setCheckBox(checkBox);
        p4.getItems().add(checkBoxSDT);

        document.saveToFile("ContentControls.docx", FileFormat.Docx);
        document.close();
    }
}

注意事项

生成后的 Word 文档需在 Microsoft Word 或其他兼容编辑器中打开，内容控件的交互功能才能正常使用。
不同版本的 Word 对控件类型的渲染可能存在细微差异，建议在 Word 2016 及以上版本中测试。
内容控件在转换为 PDF 或图片格式时，会保留显示样式，但其交互功能将不再可用。

小结

本文介绍了在 Java 中使用 Spire.Doc for Java 向 Word 文档添加几种常见内容控件的方法，包括纯文本控件、下拉列表控件、日期选择器和复选框。这类操作对于构建可填写的文档模板或实现文档自动化具有一定参考价值。根据实际业务场景，还可以进一步扩展控件的样式或验证规则。