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

Word文档中的内容控件（如下拉列表、复选框等）是规范化填写的关键。在Java开发中，高效读取并修改这些控件内容是一项常见需求。本文将通过代码示例演示具体实现方法。

本文将展示如何通过第三方库程序化地操控Word文档中的各类内容控件，涵盖文本、下拉列表、复选框等类型。所有操作均基于API完成，无需手动介入。文中以某第三方库为例，其他类似库可参考类推。

环境准备

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

    
        myrepo
        https://repo.example.com/maven-public/
    


    
        com.example
        doclib
        14.6.0
    

对于不使用Maven的项目，也可从Maven中央仓库或其他可信源获取jar包后手动导入。

内容控件的基本概念

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

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

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

文档的加载与 SDT 的获取

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

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()获取内部段落并设置新文本。

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。该库提供了getSDTControlDropDownList()方法获取下拉项集合，可遍历候选项或直接设置当前选中项。

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()方法设定勾选状态。

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

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

修改日期选择器控件

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

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元素，确保不遗漏。

递归逻辑的基本思路：

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

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

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);
        }
    }
}

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

注意事项

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

结语

通过第三方库的结构化操作，开发者能精准控制Word文档中的各类内容控件。无论是自动填表还是批量处理，掌握这些技巧均能显著提升工作效率。希望本文能为同类需求提供参考。