PDFBox向iText签名PDF添加签名字段后无法找到新增字段的问题

我有一个通过iText添加了若干签名的PDF文件，使用PDFBox 3.0.4版本，通过createEmptySignature()方法（字段名如asb_191025_0）向该PDF添加签名字段，随后用doc.saveIncremental()保存文件。此时通过inspectFields()（基于PDFBox官方示例的printFields()）可以看到新增字段已添加，但再次打开该文件准备签名时，inspectFields()仅返回原有的2个iText签名字段，调用acroForm.getField("asb_191025_0")返回null。不过在Acrobat和Notepad++中打开文件时，所有字段均可见。该问题仅在向iText签名的PDF添加字段时出现，空白PDF无此问题。

public static void createEmptySignature(PDDocument doc, int pageIndex, PDRectangle rect, String fieldName) throws Exception {
    PDAcroForm acroForm = doc.getDocumentCatalog().getAcroForm();
    if (acroForm == null) {
        acroForm = new PDAcroForm(doc);
        doc.getDocumentCatalog().setAcroForm(acroForm);
    }
    
    if(acroForm.getFields() instanceof AbstractList){
        acroForm.setFields(new ArrayList<>());
    }
    
    inspectFields(acroForm);

    PDSignatureField signatureField = new PDSignatureField(acroForm);
    signatureField.setPartialName(fieldName);
    PDAnnotationWidget widget = signatureField.getWidgets().get(0);
    widget.setRectangle(rect);
    widget.setPage(doc.getPage(pageIndex));
    widget.setPrinted(true);

    doc.getPage(pageIndex).getAnnotations().add(widget);

    acroForm.getFields().add(signatureField);
}

问题核心出在这段代码的逻辑缺陷：

if(acroForm.getFields() instanceof AbstractList){
    acroForm.setFields(new ArrayList<>());
}

处理已签名PDF时，PDFBox返回的字段列表是不可修改的内部集合（并非AbstractList子类），导致条件判断不触发。后续新增字段仅被添加到内存临时列表，没有真正同步到AcroForm的底层字段集合；而空白PDF的字段列表本身是可修改的ArrayList，所以逻辑能正常生效。

同时，增量保存已签名PDF时，PDFBox对AcroForm的更新有特殊处理，需确保字段被正确加入字段树。

修正方案：

1. 移除无效的AbstractList判断，强制将不可修改的字段列表转为可修改集合：

List<PDField> fields = new ArrayList<>(acroForm.getFields());
acroForm.setFields(fields);

2. 添加字段后调用refreshFieldTree()同步字段树，确保增量保存时字段信息被正确写入：

acroForm.getFields().add(signatureField);
acroForm.refreshFieldTree();

3. 设置NeedAppearances属性，确保阅读器能正确渲染新增字段：

acroForm.setNeedAppearances(true);

完整修正后的代码：

public static void createEmptySignature(PDDocument doc, int pageIndex, PDRectangle rect, String fieldName) throws Exception {
    PDAcroForm acroForm = doc.getDocumentCatalog().getAcroForm();
    if (acroForm == null) {
        acroForm = new PDAcroForm(doc);
        doc.getDocumentCatalog().setAcroForm(acroForm);
        acroForm.setNeedAppearances(true);
    } else {
        // 转换为可修改的字段列表
        List<PDField> fields = new ArrayList<>(acroForm.getFields());
        acroForm.setFields(fields);
        acroForm.setNeedAppearances(true);
    }

    inspectFields(acroForm);

    PDSignatureField signatureField = new PDSignatureField(acroForm);
    signatureField.setPartialName(fieldName);
    PDAnnotationWidget widget = signatureField.getWidgets().get(0);
    widget.setRectangle(rect);
    widget.setPage(doc.getPage(pageIndex));
    widget.setPrinted(true);

    doc.getPage(pageIndex).getAnnotations().add(widget);

    acroForm.getFields().add(signatureField);
    acroForm.refreshFieldTree(); // 同步字段树
}

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