Java 中的 Word 变量管理：添加、统计、获取与删除

在日常的办公自动化开发中，Word 文档的动态内容生成是一个常见需求。通常，大家首先想到的是使用"查找并替换"功能。然而，当文档结构复杂或需要全局统一更新特定数据时，文档变量提供了一种更直接的解决方案。

文档变量本质上是以键值对形式存储在 Word 文档元数据中的信息。通过在文档正文中插入变量域（DocVariable），可以实现"一处赋值，全篇同步"。本文将介绍如何利用 Java 语言，借助 Spire.Doc for Java 库，在不依赖 Microsoft Word 环境的情况下，对 Word 文档中的变量进行添加、统计、检索和删除操作。

1. 开发准备

在开始编码之前，需要在项目中引入 Spire.Doc for Java 库。该库提供了一组 API 用于操作 Word 文档结构。

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

xml 复制代码

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

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

对于非 Maven 项目，可以手动下载 JAR 包并添加到 classpath 中。

2. 添加文档变量

在 Word 中添加变量包含两个逻辑步骤：在文档正文中放置字段（定义变量引用），以及在文档属性集合中添加键值对（完成变量赋值）。

以下代码演示了如何创建一个包含变量 Term 的 Word 文档，并为其赋值为 Time。

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FieldType;
import com.spire.doc.FileFormat;
import com.spire.doc.Section;
import com.spire.doc.documents.Paragraph;

public class AddVariableDemo {
    public static void main(String[] args) {
        // 创建文档实例
        Document doc = new Document();
        Section section = doc.addSection();
        Paragraph paragraph = section.addParagraph();

        // 在段落中插入变量域，参数 "Term" 是变量的引用名称
        paragraph.appendField("Term", FieldType.Field_Doc_Variable);
        paragraph.appendText(" is a fundamental concept in physics.\r\n");
        paragraph.appendField("Term", FieldType.Field_Doc_Variable);
        paragraph.appendText(" has a measurable physical quantity.");

        // 通过 VariableCollection 添加变量值，将 Key 为 "Term" 的变量赋值为 "Time"
        doc.getVariables().add("Term", "Time");

        // 更新文档域（这行代码确保变量值正确显示）
        doc.isUpdateFields(true);

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

运行上述代码后，生成的 Word 文档中将会显示："Time is a fundamental concept in physics. Time has a measurable physical quantity."

3. 统计变量数量

在处理现有文档时，可能需要先了解其中包含的变量个数，以便进行后续逻辑判断或批量处理。

可以通过 Document.getVariables().getCount() 方法获取文档中的变量总数。

java 复制代码

import com.spire.doc.Document;

public class CountVariablesDemo {
    public static void main(String[] args) {
        // 加载之前生成的文档
        Document doc = new Document();
        doc.loadFromFile("AddVariables.docx");

        // 获取变量集合中的元素个数
        int count = doc.getVariables().getCount();
        System.out.println("当前文档包含的变量数量: " + count);
        // 输出结果: 当前文档包含的变量数量: 1
        doc.close();
    }
}

4. 检索变量的名称与值

VariableCollection 支持通过索引或变量名两种方式来检索数据。这允许遍历整个变量集合，检查文档中已经定义了哪些变量。

getNameByIndex(index): 根据索引获取变量名。
getValueByIndex(index): 根据索引获取变量值。
get(name): 根据变量名直接获取值。

java 复制代码

import com.spire.doc.Document;

public class RetrieveVariablesDemo {
    public static void main(String[] args) {
        Document doc = new Document();
        doc.loadFromFile("AddVariables.docx");

        // 通过索引检索（通常用于遍历）
        String name = doc.getVariables().getNameByIndex(0);
        String valueByIndex = doc.getVariables().getValueByIndex(0);
        System.out.println("索引0对应的变量名: " + name);
        System.out.println("索引0对应的变量值: " + valueByIndex);

        // 通过变量名直接检索值
        String valueByName = doc.getVariables().get("Term");
        System.out.println("变量 'Term' 的值为: " + valueByName);

        doc.close();
    }
}

5. 删除文档变量

对于不再需要的变量，可以通过 remove 方法从集合中清理。需要注意的是，如果仅在正文中删除了变量域的显示，而未调用 remove 方法，该变量依然作为元数据存储在文档中。

java 复制代码

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

public class RemoveVariablesDemo {
    public static void main(String[] args) {
        Document doc = new Document();
        doc.loadFromFile("AddVariables.docx");

        // 根据变量名执行删除操作
        doc.getVariables().remove("Term");
        
        // 建议更新域，删除变量后，原来的域代码通常会显示为空或变为默认值
        doc.isUpdateFields(true);

        // 保存清理后的新文档
        doc.saveToFile("RemoveVariables.docx", FileFormat.Docx_2013);
        System.out.println("变量已移除");
        doc.dispose();
    }
}

6. 变量更新机制说明

在操作文档变量时，有两个需要留意的细节。第一是显式更新域，设置值后应调用 doc.isUpdateFields(true)，否则 Word 在打开文档时可能仍会显示旧的缓存值或错误的占位符 <<Term>>。第二是域代码与显示结果的切换，在 Word 中按下 Alt+F9 可以切换显示域代码（如 { DOCVARIABLE Term }）或域值（如 Time）；在使用上述 API 时，UpdateFields 控制的是值的最终渲染。

总结

通过上述示例可以看出，利用 Spire.Doc for Java 操作 Word 文档变量的流程相对直接，代码量较少。相比于传统的字符串替换，使用文档变量的优势在于操作精准，不会误替换文档中的普通文本；同时具备全局性，只需修改变量集合中的值，文档中所有引用该变量的地方即可自动同步。此外，变量作为元数据存储，便于作为模板引擎的底层数据占位机制。这种方案在处理标准化合同、报告封面等需要动态填充业务数据的场景中，具备一定的实用价值。