Java PDFBox修改PDTextField字体及捷克语编码问题排查

问题背景 #

我正在处理带文本表单的PDF模板，需要插入捷克语文本，因此加载了支持特殊字符的字体：

PDFont formFont = PDType0Font
        .load(doc,
              PDFGenerator.class.getResourceAsStream(
                      "/fonts/AbhayaLibre-Regular.ttf"),
              false);

PDAcroForm acroForm = doc.getDocumentCatalog().getAcroForm();
PDResources resources = acroForm.getDefaultResources();
String fontName = resources.add(formFont).getName();

然后用以下代码为字段设置字体：

PDTextField template = (PDTextField) acroForm.getField("main_text");
template.setMultiline(template.isMultiline());
template.setDefaultAppearance(template.getDefaultAppearance()
                                      .replaceAll("/\\w+", "/"
                                                           + fontName));
template.setValue("Ahoj světe");

这段代码在LibreOffice创建的模板中正常运行，但在某在线PDF表单生成工具创建的模板中触发编码错误：

Exception in thread "main" java.lang.IllegalArgumentException: U+011B ('ecaron') is not available in the font Helvetica, encoding: WinAnsiEncoding
at org.apache.pdfbox.pdmodel.font.PDType1Font.encode(PDType1Font.java:410)
at org.apache.pdfbox.pdmodel.font.PDFont.encode(PDFont.java:337)

通过新建PDTextField并复制原字段属性的方式可以解决问题，代码如下：

PDFont formFont = PDType0Font
        .load(doc,
              PDFGenerator.class.getResourceAsStream(
                      "/fonts/AbhayaLibre-Regular.ttf"),
              false);


PDAcroForm acroForm = doc.getDocumentCatalog().getAcroForm();
PDResources resources = acroForm.getDefaultResources();
final String fontName = resources.add(formFont).getName();

PDPage page = doc.getPage(0);
PDTextField template = (PDTextField) acroForm.getField("main_text");
PDTextField implementation = new PDTextField(acroForm);

implementation.setPartialName(
        template.getPartialName() + "_generated");
implementation.setMultiline(template.isMultiline());
implementation.setDefaultAppearance(template.getDefaultAppearance()
                                            .replaceAll("/\\w+", "/"
                                                                 + fontName));
implementation.getWidgets().get(0).setRectangle(
        template.getWidgets().get(0).getRectangle());
implementation.getWidgets().get(0).setPage(page);
implementation.setValue("Ahoj světe");
page.getAnnotations().add(implementation.getWidgets().get(0));
acroForm.getFields().add(implementation);

template.setReadOnly(true);
template.setValue(null);

doc.save("1.pdf");

调试发现 #

调用setDefaultAppearance后，字段的默认外观已更新，但Widget的默认外观可能保持不变：

System.out.println("Old field default appearance: "
                   + template.getDefaultAppearance());
System.out.println("Old widget default appearance: "
                   + template.getWidgets().get(0).getCOSObject()
                             .getString(COSName.DA));
String newAppearance = template.getDefaultAppearance()
                               .replaceAll("/\\w+", "/"
                                                    + fontName);
template.setDefaultAppearance(newAppearance);
System.out.println("New field default appearance: "
                   + template.getDefaultAppearance());
System.out.println("New widget default appearance: "
                   + template.getWidgets().get(0).getCOSObject()
                             .getString(COSName.DA));

某在线工具模板的调试输出：

Old field default appearance: /Helv 18 Tf 0.129 0.129 0.129 rg
Old widget default appearance: /Helv 18 Tf 0.129 0.129 0.129 rg
New field default appearance: /F3 18 Tf 0.129 0.129 0.129 rg
New widget default appearance: /Helv 18 Tf 0.129 0.129 0.129 rg

LibreOffice模板的调试输出：

Old field default appearance: 1 1 1 rg /He 10.006 Tf
Old widget default appearance: 1 1 1 rg /He 10.006 Tf
New field default appearance: 1 1 1 rg /F4 10.006 Tf
New widget default appearance: 1 1 1 rg /F4 10.006 Tf

删除Widget的DA属性后可解决问题，但仍有三个疑问：

1. 为何setDefaultAppearance有时修改Widget的DA，有时不修改？
2. 是否存在设置字段外观的方式，避免被其他对象覆盖？
3. 除Widget外，还有哪些对象可能覆盖字段外观？

使用版本：pdfbox 3.0.2

解答 #

1. 为何setDefaultAppearance行为不一致？ #

这取决于PDF模板的字段结构：

• PDF表单字段的默认外观（DA）可以在字段级和Widget级分别定义。当字段本身没有DA属性时，会继承Widget的DA；反之，若字段已定义DA，Widget的DA可能独立存在。
• LibreOffice生成的模板中，字段和Widget共享同一DA引用（或字段DA优先，修改字段DA会同步更新Widget）；而某在线工具生成的模板中，字段和Widget各自存储独立的DA值，调用setDefaultAppearance仅更新字段级DA，不会自动同步到Widget。

2. 如何避免外观被覆盖？ #

要确保字体设置生效，需要同时更新字段级和Widget级的默认外观：

// 更新字段DA
String newDA = template.getDefaultAppearance().replaceAll("/\\w+", "/" + fontName);
template.setDefaultAppearance(newDA);
// 同步更新所有Widget的DA
for (PDAnnotationWidget widget : template.getWidgets()) {
    widget.getCOSObject().setString(COSName.DA, newDA);
}

这种方式直接修改所有关联Widget的DA，确保字段和Widget使用同一字体设置，避免优先级冲突。

3. 还有哪些对象可能覆盖字段外观？ #

除了Widget的DA，以下对象也可能影响最终显示：

• 表单级默认资源：AcroForm的默认资源字典若定义了默认字体，可能在字段未指定字体时被使用。
• Widget的外观流（AP）：如果Widget已经预先生成了静态外观流（Normal/On/Off状态），即使修改DA，PDF阅读器可能优先使用已生成的AP而非动态渲染。此时需要删除旧的AP，强制阅读器重新基于DA渲染：

  widget.getCOSObject().removeItem(COSName.AP);
  

• 字段的默认样式字典（DS）：部分PDF会用DS存储字段的默认样式，优先级可能高于DA。

处理PDF表单外语文本的正确方式 #

1. 加载支持目标语言的字体：确保使用包含所有特殊字符的Type0或TrueType字体，并添加到AcroForm的默认资源中。
2. 同步更新字段和所有Widget的DA：不要只修改字段级DA，必须遍历所有关联Widget，同步更新它们的外观属性。
3. 清除旧的外观流：若Widget存在预生成的AP，删除它以强制阅读器使用新的DA动态渲染文本。
4. 验证编码兼容性：避免使用仅支持WinAnsiEncoding的字体（如Helvetica），确保字体覆盖目标语言的所有字符集。

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