iText 7：为重复出现的按钮字段设置图片失败求助

你遇到的这个报错是iText 7.1.4版本处理共享表单字段（也就是你说的多次出现的同名按钮）时的一个小坑：直接调用button.setImage()后执行flattenFields()，内部生成按钮外观的逻辑会尝试创建空文本段落，触发Text初始化的参数非法异常（从错误栈里的com.itextpdf.layout.element.Text.<init>(Text.java:69)也能看出来）。

要解决这个问题，我们需要绕过默认的setImage()方法，手动为每个按钮实例生成带图片的外观，具体步骤和修正后的代码如下：

解决方案代码 #

ByteArrayOutputStream outStr = new ByteArrayOutputStream(); 
PdfDocument pdfDocument = new PdfDocument(new PdfReader(pdfStr), new PdfWriter(outStr)); 
PdfAcroForm acroForm = PdfAcroForm.getAcroForm(pdfDocument, false); 

// 获取名为"image"的主按钮字段（重复字段是它的子实例）
PdfButtonFormField mainButton = (PdfButtonFormField) acroForm.getField("image");

// 加载目标图片
ImageData imageData = ImageDataFactory.create("src/test/resources/my_image.png");

// 遍历所有重复的按钮实例（主字段的子字段）
for (PdfFormField field : mainButton.getKids()) {
    if (field instanceof PdfButtonFormField) {
        PdfButtonFormField buttonInstance = (PdfButtonFormField) field;
        // 获取按钮的区域大小
        Rectangle buttonRect = buttonInstance.getWidgets().get(0).getRectangle().toRectangle();
        
        // 创建对应大小的FormXObject作为外观载体
        PdfFormXObject appearanceXObject = new PdfFormXObject(buttonRect);
        Canvas canvas = new Canvas(appearanceXObject, pdfDocument);
        
        // 准备图片并调整大小适配按钮
        Image image = new Image(imageData);
        image.scaleToFit(buttonRect.getWidth(), buttonRect.getHeight());
        image.setFixedPosition(buttonRect.getLeft(), buttonRect.getBottom());
        
        // 将图片绘制到外观上
        canvas.add(image);
        canvas.close();
        
        // 为按钮设置正常状态的外观
        buttonInstance.setAppearance(PdfName.N, appearanceXObject.getPdfObject());
    }
}

acroForm.flattenFields(); 
pdfDocument.close();

为什么这个方法有效？ #

在iText 7.1.4中，setImage()方法的实现没有考虑到共享字段多实例的场景，内部逻辑在生成外观时会错误地尝试创建空文本段落。而手动为每个子字段（也就是每个重复的按钮实例）单独创建图片外观，既能确保所有按钮都显示图片，又能绕过那个触发异常的空文本创建逻辑。

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