基于iText5 Maven的PDF多页批量添加TextField问题排查

看起来你在使用iText5给多页PDF批量添加表单字段时遇到了「只能显示单个字段」的问题，我来帮你拆解下核心问题并给出修复方案：

问题根源 #

你当前的实现有两个关键问题导致多字段无法正常显示：

1. 注解关联错误：你用cb.addAnnotation(field.getTextField(), false)添加字段时，第二个参数false表示这个注解是「直接对象」，不会被自动关联到当前页面的注解列表中，最终只有最后一个字段能被PDF阅读器识别。
2. 不必要的重复操作：在循环处理每个字段时重复执行cb = writer.getDirectContent()，这不仅冗余，还可能干扰注解的添加流程。

修复后的完整代码 #

我调整了你的代码，同时优化了性能和健壮性，比如复用字体、修正坐标计算、确保字段正确关联到页面等：

public byte[] setupDocument(EditPdfDTO editPdfDTOList, MultipartFile attachment) {
    // 用字节流输出替代本地文件，更适合接口场景
    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
    Document document = null;
    PdfWriter writer = null;
    PdfImportedPage page = null;
    PdfReader reader = null;
    BaseFont baseFont = null;
    
    try {
        // 提前初始化字体，避免循环内重复创建
        baseFont = BaseFont.createFont(BaseFont.HELVETICA, BaseFont.WINANSI, BaseFont.NOT_EMBEDDED);
        
        // 初始化输出文档
        document = new Document(PageSize.A4);
        document.setMargins(0, 0, 0, 0);
        writer = PdfWriter.getInstance(document, outputStream);
        document.open();
        PdfContentByte cb = writer.getDirectContent();
        
        // 加载源PDF
        reader = new PdfReader(attachment.getBytes());
        int totalPages = reader.getNumberOfPages();
        
        // 确保AcroForm结构存在，开启外观生成（否则字段可能不显示）
        AcroFields acroFields = writer.getAcroFields();
        acroFields.setGenerateAppearances(true);
        
        for (int i = 0; i < totalPages; i++) {
            int currentPageNum = i + 1;
            // 导入当前页
            page = writer.getImportedPage(reader, currentPageNum);
            document.newPage();
            cb.addTemplate(page, 0, 0);
            
            // 遍历所有字段，筛选当前页需要添加的字段
            for (EditPdfFieldDTO fieldItem : editPdfDTOList.getPdf()) {
                if (fieldItem.getPageNo() == currentPageNum) {
                    int x = fieldItem.getxCoordinate();
                    int y = fieldItem.getyCoordinate();
                    String textContent = fieldItem.getTextContent();
                    float fontSize = 10f;
                    
                    // 修正字段矩形区域计算，确保能完整容纳文本
                    float textDescent = baseFont.getDescentPoint(textContent, fontSize);
                    float textAscent = baseFont.getAscentPoint(textContent, fontSize);
                    float fieldWidth = baseFont.getWidthPoint(textContent, fontSize) + 10; // 留10px边距
                    float fieldHeight = textAscent - textDescent + 10;
                    Rectangle fieldRect = new Rectangle(x, y + textDescent, x + fieldWidth, y + textAscent + 10);
                    
                    // 生成唯一字段名，避免冲突
                    String uniqueFieldName = "user_field_" + UUID.randomUUID();
                    
                    // 创建并配置TextField
                    TextField textField = new TextField(writer, fieldRect, uniqueFieldName);
                    textField.setFont(baseFont);
                    textField.setFontSize(fontSize);
                    textField.setOptions(TextField.MULTILINE | TextField.READ_ONLY);
                    textField.setTextColor(BaseColor.RED);
                    textField.setText(textContent);
                    textField.setBorderWidth(1);
                    
                    // 关键：将字段关联到当前页面并添加
                    PdfAnnotation fieldAnnotation = textField.getTextField();
                    fieldAnnotation.setPlaceInPage(currentPageNum);
                    writer.addAnnotation(fieldAnnotation);
                }
            }
        }
    } catch (DocumentException | IOException e) {
        e.printStackTrace();
        // 这里可以根据业务需求添加异常处理逻辑，比如抛出自定义异常
    } catch (Exception e) {
        e.printStackTrace();
    } finally {
        // 确保资源正确关闭
        if (document != null) {
            document.close();
        }
        if (reader != null) {
            reader.close();
        }
    }
    return outputStream.toByteArray();
}

关键优化说明 #

1. 字节流输出替代本地文件：避免依赖本地路径，直接返回生成的PDF字节数组，更适合接口场景。
2. 字体复用：把BaseFont的创建移到循环外，减少性能损耗和潜在异常。
3. 正确关联字段到页面：通过fieldAnnotation.setPlaceInPage(currentPageNum)指定字段所属页面，再用writer.addAnnotation()添加，确保每个字段都被正确加入页面的注解列表。
4. 修正矩形计算：调整坐标逻辑，保证字段区域能完整容纳文本内容，不会出现截断或位置偏移。
5. 开启外观生成：acroFields.setGenerateAppearances(true)确保PDF阅读器能正确渲染字段的样式。
6. 唯一字段名：用UUID生成唯一字段名，避免同名字段覆盖。

额外小建议 #

• 可以提前把editPdfDTOList.getPdf()按页面号分组（比如用Map<Integer, List<EditPdfFieldDTO>>），这样循环页面时直接取对应页的字段，不用每次遍历整个列表，提升性能。
• 异常处理可以更精细化，比如捕获字体创建失败时，记录明确的日志或抛出业务异常，方便排查问题。

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