Java 实战：精准操控 Word 文档中的内容控件

在日常的文档处理任务中，我们经常遇到包含内容控件的 Word 文档。内容控件是 Word 中一种强大的结构化文档工具，它们以特定的形式（如下拉列表、日期选择器、纯文本域、复选框等）出现，帮助用户规范化地填写和展示信息。在 Java 程序中，如何高效、精准地读取并修改这些控件的内容，是一个常见的开发需求。

本篇文章将演示如何通过第三方库来操作 Word 文档中的多种内容控件，包括文本控件、下拉列表控件、复选框控件等。所有操作均基于编程接口完成，无需手动干预。文中以 Spire.Doc for Java 为例，同类库的操作思路可参考类推。

环境准备

在开始编码之前，需要在 Java 项目中引入相关依赖。以 Maven 项目为例，在 pom.xml 中添加如下配置：

xml 复制代码

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <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 的项目，也可以通过 Maven 中央仓库或其他可信源获取 jar 包后手动导入。

内容控件的基本概念

在 Word 中，内容控件位于"开发工具"选项卡下，常用类型包括：

纯文本控件：允许用户输入纯文本。
格式文本控件：允许用户输入带格式的文本。
下拉列表控件：提供一组预定义的选项，用户只能从中选择。
复选框控件：表示是/否或选中/未选中的状态。
日期选择器控件：提供日历界面，用于选择日期。

在 Spire.Doc 中，这些控件被统一抽象为 StructureDocumentTag 对象（简称 SDT）。通过 SDT 的属性，可以判断控件的类型，并以不同方式进行读写操作。

文档的加载与 SDT 的获取

首先，加载一个包含内容控件的 Word 文档，并获取其所有的 SDT 对象：

java 复制代码

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

public class ModifyContentControls {
    public static void main(String[] args) {
        // 加载 Word 文档
        Document doc = new Document();
        doc.loadFromFile("sample.docx");

        // 遍历文档中的所有 SDT
        for (int i = 0; i < doc.getSections().getCount(); i++) {
            Section section = doc.getSections().get(i);
            for (int j = 0; j < section.getBody().getChildObjects().getCount(); j++) {
                DocumentObject obj = section.getBody().getChildObjects().get(j);
                if (obj instanceof StructureDocumentTag) {
                    StructureDocumentTag sdt = (StructureDocumentTag) obj;
                    processSDT(sdt);
                }
            }
        }

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

    private static void processSDT(StructureDocumentTag sdt) {
        // 将在后面实现具体逻辑
    }
}

上面的代码片段展示了如何将文档中每个 SDT 元素提取出来，并交由 processSDT 方法进行个性化处理。接下来，针对不同类型的控件编写处理逻辑。

修改纯文本与格式文本控件

对于纯文本（Plain Text）控件，其 SDT 的类型为 SdtType.Plain_Text。如果要修改其内容，可以直接通过 getSDTContent() 获取内部的文本段落并设置新文本。

java 复制代码

if (sdt.getSDTType() == SdtType.Plain_Text) {
    // 获取 SDT 内的段落
    TextRange textRange = sdt.getSDTContent().getParagraphs().get(0).getChildObjects().get(0) instanceof TextRange
            ? (TextRange) sdt.getSDTContent().getParagraphs().get(0).getChildObjects().get(0)
            : null;
    if (textRange != null) {
        textRange.setText("新的纯文本内容");
    }
}

格式文本控件（Rich Text）的类型为 SdtType.Rich_Text，其内容与纯文本控件操作方式基本一致，也是通过内部段落对象来修改。若需要清除原格式并写入新的带格式文本，可以分别设置段落的样式或直接替换段落的文本元素。

修改下拉列表控件

下拉列表控件（Drop-Down List）的类型为 SdtType.Drop_Down_List。Spire.Doc 提供了 getSDTControlDropDownList() 方法来获取下拉项集合，可以遍历所有候选项，或者直接设置当前选中项。

java 复制代码

if (sdt.getSDTType() == SdtType.Drop_Down_List) {
    DropDownList list = sdt.getSDTControlDropDownList();
    // 打印所有可选项
    for (int k = 0; k < list.getDropDownItems().getCount(); k++) {
        System.out.println("选项: " + list.getDropDownItems().get(k).getDisplayText());
    }
    // 设置选中项（根据显示文本或值）
    if (list.getDropDownItems().getCount() > 1) {
        list.setSelectedItemIndex(1); // 选中第二个选项
    }
}

需要注意，如果设置的 SelectedItemIndex 超出了项集合的范围，将会导致异常。在实际使用中最好进行边界判断。

修改复选框控件

复选框控件（Check Box）的类型为 SdtType.Check_Box。通过 getSDTControlCheckBox() 方法可以获取复选框对象，并通过 setChecked() 方法来设定其勾选状态。

java 复制代码

if (sdt.getSDTType() == SdtType.Check_Box) {
    CheckBox checkBox = sdt.getSDTControlCheckBox();
    checkBox.setChecked(true); // 勾选复选框
    // checkBox.setChecked(false); // 取消勾选
}

复选框的状态是一个布尔值，修改后保存文档即可反映出对应的勾选状态。

修改日期选择器控件

日期选择器控件（Date Picker）的类型为 SdtType.Date_Picker。可以通过 getSDTControlDatePicker() 获取日期选择器对象，并调用 setDate() 方法来更改当前日期。

java 复制代码

import java.util.Calendar;

if (sdt.getSDTType() == SdtType.Date_Picker) {
    DatePicker datePicker = sdt.getSDTControlDatePicker();
    Calendar calendar = Calendar.getInstance();
    calendar.set(2025, 6, 20);  // 月份从0开始，6代表7月
    datePicker.setDate(calendar);
}

日期设置后，文档中会展示为对应的短日期格式。格式的具体显示方式取决于控件定义的日期格式。

处理嵌套内容控件

在复杂的 Word 文档中，内容控件可能存在嵌套关系。例如，一个格式文本控件内部可能包含另一个纯文本控件。单纯遍历段落级别的子对象可能会遗漏这些嵌套的 SDT。因此在批量处理时，可以考虑递归方法遍历 SDTContent 的子对象，查找并处理其中的所有 SDT 元素，保证不遗漏。

递归逻辑的基本思路：

遍历当前容器（Section、Body、SDT 内部）的所有子对象；
若子对象是 StructureDocumentTag，则处理该 SDT，并进一步递归处理其 SDTContent 的子对象；
若子对象是段落或表格等复杂对象，则继续向其内部递归查找。

以下是一个简单的递归遍历示例：

java 复制代码

private static void processSDTRecursive(StructureDocumentTag sdt) {
    processSDT(sdt); // 处理当前 SDT
    // 遍历 SDT 内容中的子对象
    for (int i = 0; i < sdt.getSDTContent().getChildObjects().getCount(); i++) {
        DocumentObject child = sdt.getSDTContent().getChildObjects().get(i);
        if (child instanceof StructureDocumentTag) {
            processSDTRecursive((StructureDocumentTag) child);
        }
    }
}

通过这种方式，即便是深度嵌套的控件，也可以被准确发现和修改。

注意事项

格式问题：修改纯文本控件时，文本格式可能会被重置为默认样式。如果需要保留样式，建议获取原有段落的格式属性并在设置新内容后重新应用。
并发与线程安全：该库的 API 并非为线程安全设计，如果在多线程环境下同时操作同一个文档对象，需要自行做好同步控制。
保存格式 ：修改完成后，建议以 Docx_2013 格式保存，这样可以最大程度兼容内容控件的各种属性。

结语

借助第三方库，开发人员能够以结构化的方式，精准地读取和修改 Word 文档中的各类内容控件。无论是实现自动填表、文档批量处理，还是生成定制化报告，掌握这些操作都将极大提升工作效率。希望本篇文章能够为有类似需求的开发者提供清晰的思路和可参考的代码范例。