如何在PDFBox 2中添加同名且带不同导出值的复选框组

你遇到的核心问题是PDF表单中同名复选框属于同一个字段的多个小部件（Widget），而不是多个独立字段。当前代码每次创建复选框时都生成新的PDCheckBox对象并添加到表单字段列表中，这会导致字段名冲突，PDF阅读器只会加载第一个同名字段，后续的会被忽略。

我们需要先检查表单中是否已存在目标名称的复选框字段：

• 如果不存在：创建新的PDCheckBox字段，并添加第一个widget
• 如果已存在：复用已有字段，仅添加新的widget到该字段中

同时要注意，setExportValues是给整个字段设置可选的导出值集合，每个widget对应其中一个导出值，需要给每个新widget指定对应的导出值（通过setAppearanceState关联）。

首先调整调用addCBField的逻辑，先检查字段是否存在：

else if ((element.getElementType().startsWith("CB"))) {
    if (element.getIsFillableFormField()) {
        List<Integer> _int_bbox_list = convertBBOXtoIntegerList(element.getBBOX());
        Integer xVal = _int_bbox_list.get(0);
        Integer yVal = pageHeight - _int_bbox_list.get(1);
        Integer width = _int_bbox_list.get(2) - _int_bbox_list.get(0);
        Integer height = _int_bbox_list.get(1) - _int_bbox_list.get(3);
        String formFieldName = null, toolTip = null, exportValue = null;
        JSONArray formFieldProperties = (JSONArray) element.getFormFieldProperties();
        // 提取当前复选框的属性
        for (Object eleObj : formFieldProperties) {
            formFieldName = (String) ((JSONObject) eleObj).get("FormFieldName");
            toolTip = (String) ((JSONObject) eleObj).get("ToolTips");
            exportValue = (String) ((JSONObject) eleObj).get("ExportValue");
        }
        // 检查表单中是否已存在该名称的复选框字段
        PDCheckBox existingCheckbox = null;
        for (PDField field : acroForm.getFields()) {
            if (field instanceof PDCheckBox && field.getPartialName().equals(formFieldName)) {
                existingCheckbox = (PDCheckBox) field;
                break;
            }
        }
        // 维护导出值列表
        List<String> exportList = new ArrayList<>();
        if (existingCheckbox != null) {
            exportList.addAll(existingCheckbox.getExportValues());
            if (!exportList.contains(exportValue)) {
                exportList.add(exportValue);
            }
        } else {
            exportList.add(exportValue);
        }
        // 调用修改后的添加方法
        addCBField(_pdfDocumentObj, acroForm, page, formFieldName, false, xVal, yVal, width, height, toolTip, exportValue, existingCheckbox, exportList);
    }
}

然后修改addCBField方法，支持复用已有字段：

private static void addCBField(PDDocument document, PDAcroForm acroForm, PDPage page, String name, boolean checked, float x, float y, float width, float height, String toolTip, String currentExportValue, PDCheckBox existingCheckbox, List<String> exportList) {
    try {
        PDCheckBox checkbox;
        PDAnnotationWidget widget;

        if (existingCheckbox != null) {
            // 复用已有字段，创建新的widget
            checkbox = existingCheckbox;
            widget = new PDAnnotationWidget();
            checkbox.getWidgets().add(widget);
        } else {
            // 创建新字段和第一个widget
            checkbox = new PDCheckBox(acroForm);
            checkbox.setPartialName(name);
            widget = checkbox.getWidgets().get(0);
            acroForm.getFields().add(checkbox);
        }

        // 设置widget基础属性
        PDRectangle rect = new PDRectangle(x, y, width, height);
        widget.setPage(page);
        widget.setRectangle(rect);
        widget.setPrinted(true);

        PDAppearanceCharacteristicsDictionary appearanceCharacteristics = new PDAppearanceCharacteristicsDictionary(new COSDictionary());
        appearanceCharacteristics.setNormalCaption("4");
        widget.setAppearanceCharacteristics(appearanceCharacteristics);

        // 配置外观流
        PDAppearanceDictionary ap = new PDAppearanceDictionary();
        widget.setAppearance(ap);
        PDAppearanceEntry normalAppearance = new PDAppearanceEntry(new COSDictionary());
        ap.setNormalAppearance(normalAppearance);
        COSDictionary normalAppearanceDict = (COSDictionary) normalAppearance.getCOSObject();
        normalAppearanceDict.setItem(COSName.Off, createCheckBoxAppearanceStream(document, widget, false));
        // 用当前导出值作为选中状态的标识
        normalAppearanceDict.setItem(COSName.getPDFName(currentExportValue), createCheckBoxAppearanceStream(document, widget, true));

        // 绑定widget与对应导出值
        widget.setAppearanceState(currentExportValue);

        // 将widget添加到页面
        page.getAnnotations().add(widget);

        // 设置字段的提示文本和完整导出值列表
        checkbox.setAlternateFieldName(toolTip);
        checkbox.setExportValues(exportList);

        // 设置选中状态
        if (checked) {
            checkbox.check(currentExportValue);
        } else {
            checkbox.unCheck();
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
}

1. 字段复用逻辑：先遍历表单字段，找到已存在的同名复选框，避免重复创建字段导致冲突
2. Widget独立创建：对于已有字段，创建新的PDAnnotationWidget并添加到字段的widget列表中，实现同一字段多选项
3. 导出值与外观绑定：每个widget的选中状态使用对应的导出值作为key，替代固定的YES，确保每个复选框对应唯一导出值
4. 导出值列表维护：确保整个字段的导出值列表包含所有同名复选框的选项，保证表单数据的正确性

这样修改后，同名的复选框会被正确识别为同一字段的多个选项，所有复选框都会在PDF中正常显示，且每个复选框对应不同的导出值。

内容的提问来源于stack exchange，提问作者Seyed Ahamed Bilal