iText7合并PDF后AcroForm字段丢失，无法设置只读问题

问题根因 #

你遇到的情况本质是PDF合并过程中未正确处理AcroForm字典。很多基础的合并逻辑只复制页面的视觉内容，忽略了表单字段的底层AcroForm结构——这就导致PDF在阅读器里能看到字段，但iText无法通过PdfAcroForm.getAcroForm()识别，因为关键的表单字典数据没被合并进去。

分步解决方案 #

1. 合并阶段主动保留AcroForm #

用iText合并PDF时，不能只单纯复制页面，必须显式处理每个源文档的AcroForm，把字段迁移到目标文档中。示例代码：

// 初始化合并后的PDF文档
PdfDocument mergedDoc = new PdfDocument(new PdfWriter("output_merged.pdf"));
// 获取或创建合并文档的AcroForm
PdfAcroForm mergedForm = PdfAcroForm.getAcroForm(mergedDoc, true);

// 遍历所有待合并的PDF文件
for (String srcPath : sourcePdfPaths) {
    try (PdfDocument srcDoc = new PdfDocument(new PdfReader(srcPath))) {
        PdfAcroForm srcForm = PdfAcroForm.getAcroForm(srcDoc, false);
        if (srcForm != null) {
            // 复制源文档的表单字段到合并文档
            mergedForm.copyFields(srcForm);
        }
        // 复制页面内容
        srcDoc.copyPagesTo(1, srcDoc.getNumberOfPages(), mergedDoc);
    }
}

mergedDoc.close();

这段代码的核心是copyFields()方法，它会把源文档的字段定义、属性完整迁移到合并后的AcroForm中，确保底层结构不丢失。

2. 修复已损坏的合并PDF #

如果已经生成了AcroForm丢失的PDF，可以通过扫描页面Widget注释的方式重建AcroForm关联：

try (PdfDocument doc = new PdfDocument(new PdfReader("broken_merged.pdf"), new PdfWriter("fixed_merged.pdf"))) {
    PdfAcroForm form = PdfAcroForm.getAcroForm(doc, true);
    
    // 遍历所有页面，找回Widget形式的字段
    for (int pageNum = 1; pageNum <= doc.getNumberOfPages(); pageNum++) {
        PdfPage page = doc.getPage(pageNum);
        PdfArray annots = page.getPdfObject().getAsArray(PdfName.Annots);
        if (annots == null) continue;
        
        for (int i = 0; i < annots.size(); i++) {
            PdfDictionary annotDict = annots.getAsDictionary(i);
            // 判断是否是表单字段的Widget注释
            if (PdfName.Widget.equals(annotDict.getAsName(PdfName.Subtype))) {
                PdfName fieldName = annotDict.getAsName(PdfName.T);
                if (fieldName != null) {
                    // 将Widget重新注册到AcroForm
                    form.addField(fieldName, annotDict, page);
                }
            }
        }
    }
}

阅读器里能看到字段，说明页面上的Widget注释还在，这段代码把这些Widget重新关联到新建的AcroForm中，让iText能识别并操作。

3. “最终化”只读设置的正确姿势 #

设置只读前，务必确保正确获取/创建AcroForm，不要盲目新建。代码示例：

try (PdfDocument doc = new PdfDocument(new PdfReader("merged.pdf"), new PdfWriter("finalized.pdf"))) {
    // 第二个参数true表示：如果没有AcroForm就创建一个
    PdfAcroForm form = PdfAcroForm.getAcroForm(doc, true);
    if (form == null) return;
    
    // 遍历所有字段设置只读
    for (PdfFormField field : form.getFormFields().values()) {
        field.setReadOnly(true);
    }
}

这里的关键是getAcroForm(doc, true)，它会自动关联页面上已有的Widget字段，避免新建空表单导致找不到字段的问题。

额外注意点 #

• 合并时如果源文档有重名字段，会导致字段覆盖，建议合并前统一重命名字段。
• 检查是否是XFA表单：如果form.isXfa()返回true，说明是XML架构的表单，需要用form.getXfaForm()来操作，而不是普通AcroForm逻辑。

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