升级flying-saucer-itext至9.1.22后图片无法渲染及字体报错问题

问题背景 #

将flying-saucer-itext从9.1.15版本升级至9.1.22后，通过Docusign 3.23 SDK获取的签名图片无法正常渲染。回退至9.1.15版本时图片可正常显示，但部署要求必须使用9.1.22版本。后续生成PDF时还出现了字体识别错误。

相关配置与代码 #

pom.xml依赖配置 #

<dependency>
      <groupId>org.xhtmlrenderer</groupId>
      <artifactId>flying-saucer-pdf-itext5</artifactId>
      <version>9.1.22</version>
      <exclusions>
        <exclusion>
          <groupId>org.bouncycastle</groupId>
          <artifactId>bcprov-jdk14</artifactId>
        </exclusion>
        <exclusion>
          <groupId>com.github.librepdf</groupId>
          <artifactId>openpdf</artifactId>
        </exclusion>
      </exclusions>
</dependency>
<dependency>     
      <groupId>com.github.librepdf</groupId>     
      <artifactId>openpdf</artifactId>     
      <version>1.3.30</version> 
</dependency>
...
 <docusign.sdk.version>3.23.0</docusign.sdk.version>

Java代码片段（隐私已截断） #

import org.stringtemplate.v4.DateRenderer;
import org.stringtemplate.v4.ST;
import org.stringtemplate.v4.STRawGroupDir;
import org.stringtemplate.v4.StringRenderer;
import org.xhtmlrenderer.pdf.ITextRenderer;
...
signatureImageStringEncoded = Base64.getEncoder().encodeToString(signatureImage);
...

ST模板渲染代码 #

<img src="data:image/gif;base64, signatureImageStringEncoded" alt="Signature" width="200" height="75"/>

后续错误信息（2023年7月6日更新） #

生成PDF时抛出以下异常：

java.lang.RuntimeException: Font 'STSong-Light,BoldItalic' with 'UniGB-UCS2-H' is not recognized.
    at org.xhtmlrenderer.pdf.ITextFontResolver.createInitialFontMap(ITextFontResolver.java:469)
    at org.xhtmlrenderer.pdf.ITextFontResolver.<init>(ITextFontResolver.java:40)
    at org.xhtmlrenderer.pdf.ITextRenderer.<init>(ITextRenderer.java:117)
    at org.xhtmlrenderer.pdf.ITextRenderer.<init>(ITextRenderer.java:102)
    at com.oncor.corp.pete.api.services.pdf.PDFService.createPDFFromTemplate(PDFService.java:49)

解决方案 #

1. 修复字体识别错误 #

这个错误是因为flying-saucer 9.1.22默认缺少中文字体支持，可通过以下两种方式解决：

• 添加字体依赖：在pom.xml中引入openpdf的字体包：

  <dependency>
      <groupId>com.github.librepdf</groupId>
      <artifactId>openpdf-fonts</artifactId>
      <version>1.3.30</version>
  </dependency>
  

• 手动注册字体：在创建ITextRenderer实例前，手动加载并注册STSong-Light字体：

  ITextRenderer renderer = new ITextRenderer();
  // 替换为实际的字体文件路径，可将字体文件放入项目resources目录
  renderer.getFontResolver().addFont("/fonts/STSong-Light.ttf", BaseFont.IDENTITY_H, BaseFont.NOT_EMBEDDED);
  

2. 修复图片渲染问题 #

升级后flying-saucer对data URI格式要求更严格，可从以下几点排查：

• 移除data URI中的多余空格：ST模板中data:image/gif;base64,后面的空格会导致解析失败，修改模板代码：

  <img src="data:image/gif;base64,<signatureImageStringEncoded>" alt="Signature" width="200" height="75"/>
  

• 验证Base64编码正确性：检查signatureImageStringEncoded是否为完整、无换行的Base64字符串，避免编码过程中引入多余字符。
• 确认图片格式：确认Docusign返回的签名图片确实是GIF格式，若为其他格式（如PNG），需同步修改data URI中的image/gif为对应格式（如image/png）。

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