使用iText PDF与Freemarker生成PDF时Base64图片显示空白求助

问题原因 #

iTextPDF的HTML转PDF组件（HtmlConverter）默认不支持解析data:image/jpg;base64,...格式的图片源——浏览器和在线工具能识别这种Data URI，但iText框架默认没有处理该格式的逻辑，这就是Base64图片显示空白的核心原因。

解决方案：自定义ImageProvider解析Data URI #

通过实现iText的IImageProvider接口，让框架能够识别并解码Base64格式的图片源，无需修改现有Freemarker模板。

1. 实现自定义ImageProvider类

import com.itextpdf.io.image.ImageData;
import com.itextpdf.io.image.ImageDataFactory;
import com.itextpdf.html2pdf.resolver.resource.IImageProvider;
import com.itextpdf.html2pdf.resolver.resource.IResourceRetriever;
import com.itextpdf.html2pdf.attach.ProcessorContext;

import java.util.Base64;

public class DataUriImageProvider implements IImageProvider {
    @Override
    public ImageData getImageData(String src, String contentType, IResourceRetriever resourceRetriever, ProcessorContext context) {
        // 识别Data URI格式的图片源
        if (src != null && src.startsWith("data:image/")) {
            String[] uriParts = src.split(",", 2);
            if (uriParts.length == 2) {
                // 解码Base64字符串为字节数组
                byte[] imageBytes = Base64.getDecoder().decode(uriParts[1].trim());
                return ImageDataFactory.create(imageBytes);
            }
        }
        // 非Data URI的情况，沿用默认逻辑加载图片
        return ImageDataFactory.create(src, resourceRetriever);
    }
}

2. 在PDF生成代码中配置自定义Provider

在调用HtmlConverter转换HTML到PDF时，将自定义的DataUriImageProvider注入到ConverterProperties中：

import com.itextpdf.html2pdf.HtmlConverter;
import com.itextpdf.html2pdf.ConverterProperties;
import java.io.FileOutputStream;
import java.io.StringWriter;

// ... 你的Freemarker模板渲染逻辑
StringWriter writer = new StringWriter();
freemarkerTemplate.process(dataModel, writer);
String renderedHtml = writer.toString();

// 配置ConverterProperties
ConverterProperties converterProps = new ConverterProperties();
converterProps.setImageProvider(new DataUriImageProvider());

// 生成PDF文件
HtmlConverter.convertToPdf(renderedHtml, new FileOutputStream("report.pdf"), converterProps);

额外检查项 #

• 确认传递给Freemarker的logo变量是标准的data:image/jpg;base64,xxxx格式，无多余换行、空格或转义字符；
• 如果是PNG格式图片，需确保MIME类型与实际格式匹配（即data:image/png;base64,...）。

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