Apache PDFBox组合字段填充异常：分段数字显示失效

你遇到的问题是PDF组合字段（Comb Field）填充后扁平化，未能呈现预期的分段字符布局。核心原因是：

• PDFBox的setComb(true)需要配合字段的**最大字符数（MaxLen）**属性才能生效，该属性决定了分段的数量；
• 原代码中未确保字段外观（Appearance）正确生成，扁平化时丢失了组合字段的视觉样式；
• 直接调用acroForm.flatten()可能会破坏组合字段的分段渲染逻辑。

1. 确保组合字段的MaxLen与目标字符长度匹配 #

组合字段的分段数由MaxLen属性决定，比如IFSC码是11位，需要将字段的MaxLen设置为11，这样每个字符会自动分配到一个分段格子中。

2. 调整字段设置顺序并刷新外观 #

修改setTextField方法，先设置MaxLen和comb属性，再赋值，最后强制刷新字段外观，确保样式生效：

private void setTextField(PDAcroForm acroForm, String fieldName, String value, boolean isCombField, int maxLength) throws IOException {
    if (value == null || value.isEmpty()) {
        return;
    }
    List<PDField> fields = acroForm.getFields();
    for (PDField field : fields) {
        if (field.getFullyQualifiedName().equals(fieldName) && field instanceof PDTextField) {
            PDTextField textField = (PDTextField) field;
            if (isCombField) {
                // 设置最大字符数，对应分段数量
                textField.setMaxLength(maxLength);
                textField.setComb(true);
            }
            textField.setValue(value);
            // 刷新外观，确保组合样式被正确渲染
            textField.getWidgets().forEach(widget -> {
                try {
                    widget.setAppearance(null); // 清除旧的外观缓存
                    textField.generateAppearance();
                } catch (IOException e) {
                    log.error("Failed to generate appearance for field: {}", fieldName, e);
                }
            });
        }
    }
}

3. 优化扁平化或改用只读模式 #

如果不需要完全扁平化表单（即保留字段但不可编辑），可以替换acroForm.flatten()为以下代码，这样组合字段的分段样式会保留：

// 启用外观生成
acroForm.setNeedAppearances(true);
// 设置表单为只读，防止用户编辑
acroForm.setReadOnly(true);

如果必须扁平化，确保在调用flatten()前已经刷新所有字段的外观，并且建议升级到PDFBox 2.0.30+版本（修复了部分组合字段扁平化的bug）。

4. 调用修改后的方法 #

以IFSC码字段为例，调用时指定最大长度为11：

setTextField(acroForm,"rectangleIfscMicr",request.getIfscCode(),true,11);
// 其他组合字段同理，比如日期字段如果是8位（DDMMYYYY），设置maxLength为8
setTextField(acroForm,"date",currentDate,true,8);
setTextField(acroForm,"fromDate",currentDate,true,8);
setTextField(acroForm,"toDate",currentDateAdded10Years,true,8);
setTextField(acroForm,"rectangleBankAcNumber",request.getAccountNumber(),true,request.getAccountNumber().length());

5. 检查字体设置 #

确保组合字段使用等宽字体（比如Courier），这样每个字符的宽度一致，分段格子会对齐。如果原PDF模板的字段字体不是等宽的，可以在代码中指定：

// 设置等宽字体（需确保字体已嵌入或系统可用）
PDFont font = PDType1Font.COURIER;
textField.setDefaultAppearance("/" + font.getName() + " 12 Tf 0 g");

内容的提问来源于stack exchange，提问作者Mohit Kumar