如何确保PDF文件名及内容中Emoji正常显示？iText问题排查

核心问题分析 #

你遇到的情况是Emoji在PDF里显示空白，但复制后能正常识别，说明iText已经正确嵌入了Emoji的字符编码，只是没有正确渲染彩色Emoji的图形——NotoColorEmoji是彩色OpenType字体，iText默认的字体渲染逻辑对这类字体支持有限，需要专门配置。

具体解决步骤 #

1. 确认依赖与字体加载正确性 #

先确保Maven依赖包含iText核心及字体相关模块：

<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext-core</artifactId>
    <version>8.0.5</version>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>font-asian</artifactId>
    <version>8.0.5</version>
</dependency>

加载Emoji字体时，指定PdfEncodings.IDENTITY_H编码以支持全Unicode字符：

PdfFont emojiFont = PdfFontFactory.createFont("path/to/NotoColorEmoji-Regular.ttf", PdfEncodings.IDENTITY_H, true);

2. 启用彩色字体渲染支持 #

iText 8默认不处理彩色字体，需通过WriterProperties显式配置：

WriterProperties writerProps = new WriterProperties();
writerProps.addUax14Processor(new DefaultUax14Processor()); // 处理复杂Emoji的字符分割
PdfWriter writer = new PdfWriter("output.pdf", writerProps);
PdfDocument pdfDoc = new PdfDocument(writer);
Document doc = new Document(pdfDoc);

3. 用字体集混合普通字体与Emoji字体 #

单独用Emoji字体无法渲染普通文本，需创建FontSet组合两类字体，让iText自动匹配字符：

FontSet fontSet = new FontSet();
fontSet.addFont("path/to/NotoSans-Regular.ttf"); // 替换成你用的普通字体
fontSet.addFont("path/to/NotoColorEmoji-Regular.ttf");

FontProvider fontProvider = new FontProvider(fontSet);
doc.setFontProvider(fontProvider);

4. 测试文本渲染 #

添加目标文本到文档：

doc.add(new Paragraph("🌹🦬🪶🐓Esphi N🤣😂"));
doc.close();

关键注意事项 #

• 确保NotoColorEmoji字体文件路径正确，避免因找不到字体触发默认字体 fallback（不支持Emoji）。
• font-asian模块是iText 8支持彩色Emoji的必要依赖，不可省略。
• 带组合逻辑的复杂Emoji需要Uax14Processor处理字符分割，否则可能显示异常。

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