Java中文PDF排版实战：iText与PDFBox解决方案

1. 为什么我们需要专门的中文PDF排版工具

第一次用Java生成包含中文的PDF文档时，我就被各种排版问题折腾得够呛。西文字符和中文混排时出现的间距不均、段落对齐不整齐、标点符号位置错乱等问题，让生成的文档看起来非常不专业。这促使我深入研究Java环境下中文PDF排版的解决方案。

中文排版与西文排版存在本质差异。中文是方块字，每个字符占据相同的视觉空间；而西文字符宽度不一，i和W的宽度能差三倍。更复杂的是中文标点符号（如逗号、句号）需要悬挂在字符边框之外，这与西文标点位于字符内部的处理方式完全不同。当系统默认使用西文排版规则处理中文时，就会出现各种视觉上的不协调。

2. 主流Java PDF生成库的中文支持对比

2.1 iText系列库的演进

iText是最早支持中文的Java PDF库之一。早期的iText 2.1.7版本需要通过手动加载中文字体来实现基本支持，但存在内存泄漏风险。现代的iText 7.x版本提供了完整的CJK（中日韩）语言支持包，内置了思源黑体等开源字体，解决了大部分基础排版问题。

java复制// iText 7 中文示例
PdfFont font = PdfFontFactory.createFont("STSong-Light", "UniGB-UCS2-H", true);
Paragraph p = new Paragraph("你好，世界！").setFont(font);
document.add(p);

2.2 Apache PDFBox的现状

PDFBox 3.0版本开始提供更好的中文支持，但需要开发者自行处理字体嵌入。它的优势在于完全免费（iText商用需要付费），适合预算有限的项目。

java复制// PDFBox 示例
PDDocument doc = new PDDocument();
PDPage page = new PDPage();
doc.addPage(page);

PDFont font = PDType0Font.load(doc, new File("SimSun.ttf"));
PDPageContentStream stream = new PDPageContentStream(doc, page);
stream.beginText();
stream.setFont(font, 12);
stream.newLineAtOffset(100, 700);
stream.showText("PDFBox中文测试");
stream.endText();
stream.close();

2.3 Flying Saucer的特别之处

这个基于iText的HTML转PDF库，适合已经熟悉CSS的开发者。通过定义@font-face规则，可以相对容易地实现中文排版：

html复制<style>
@font-face {
    font-family: SimSun;
    src: url(file:///fonts/SimSun.ttf);
}
body { font-family: SimSun; }
</style>

3. 中文对齐的核心技术解析

3.1 标点符号的特殊处理

中文标点需要实现"避头尾"规则：某些标点（如逗号、句号）不能出现在行首，引号、书名号等不能出现在行尾。在Java中实现这一规则需要：

1. 定义标点字符集
2. 在换行算法中加入特殊判断
3. 必要时调整字符间距

java复制// 简单的避头尾实现示例
String punctuation = "，。、；：？！""''（）【】《》";
if (punctuation.contains(currentChar)) {
    adjustLineBreakPosition();
}

3.2 文本对齐的四种方式

中文PDF通常采用以下对齐方式：

1. 两端对齐：通过调整字间距使文本左右边缘整齐
2. 左对齐：自然排列，右侧不强制对齐
3. 居中对齐：常用于标题
4. 右对齐：用于落款等特殊情况

重要提示：两端对齐时，最后一行的处理很关键。专业排版中，最后一行应该左对齐而非强行拉伸。

3.3 字间距与行间距的黄金比例

中文排版推荐：

• 行间距：字高的1.5-2倍
• 段间距：行间距的1.5倍
• 字间距：通常为0，两端对齐时可适当调整但不超过字宽的10%

java复制// iText 行间距设置示例
Paragraph p = new Paragraph("内容")
    .setMultipliedLeading(1.5f); // 1.5倍行距

4. 实战：构建中文PDF生成工具类

4.1 字体管理最佳实践

建议将常用中文字体预加载到内存中，避免重复IO操作：

java复制public class FontManager {
    private static final Map<String, PdfFont> FONT_CACHE = new HashMap<>();
    
    public static PdfFont getFont(String name) {
        if (!FONT_CACHE.containsKey(name)) {
            FONT_CACHE.put(name, PdfFontFactory.createFont("fonts/" + name + ".ttf"));
        }
        return FONT_CACHE.get(name);
    }
}

4.2 段落样式模板化

定义常用样式模板，确保全文档风格统一：

java复制public class StyleTemplate {
    public static Paragraph createTitleStyle(String text) {
        return new Paragraph(text)
            .setFont(FontManager.getFont("SimHei"))
            .setFontSize(16)
            .setTextAlignment(TextAlignment.CENTER)
            .setMarginBottom(15);
    }
    
    public static Paragraph createBodyStyle(String text) {
        return new Paragraph(text)
            .setFont(FontManager.getFont("SimSun"))
            .setFontSize(12)
            .setTextAlignment(TextAlignment.JUSTIFIED)
            .setFirstLineIndent(24)
            .setMultipliedLeading(1.8f);
    }
}

4.3 复杂排版示例：图文混排

java复制// 创建两栏布局
Document document = new Document(pdfDoc);
float width = pdfDoc.getDefaultPageSize().getWidth();
float margin = 50;
float columnWidth = (width - 3 * margin) / 2;

// 左栏文本
ColumnDocumentRenderer renderer = new ColumnDocumentRenderer(
    document, new Rectangle[]{
        new Rectangle(margin, margin, columnWidth, 800),
        new Rectangle(margin + columnWidth + margin, margin, columnWidth, 800)
    });
document.setRenderer(renderer);

// 添加内容
document.add(StyleTemplate.createTitleStyle("中文排版指南"));
document.add(StyleTemplate.createBodyStyle("这里是详细的正文内容..."));

// 添加图片
ImageData imageData = ImageDataFactory.create("chart.png");
Image image = new Image(imageData);
image.setAutoScale(true);
document.add(image);

5. 常见问题与解决方案

5.1 字体显示为方框

原因：未正确嵌入中文字体
解决：

1. 确认字体路径正确
2. 检查字体是否支持目标字符集
3. 确保调用了PdfFontFactory.createFont()而非使用基础字体

5.2 中文换行位置不正确

原因：未正确处理中文分词规则
解决：

1. 实现自定义的换行策略
2. 使用iText的Asian字体特性
3. 设置合适的字符间距

java复制Paragraph p = new Paragraph(text)
    .setFont(asianFont)
    .setProperty(Property.LINE_BREAK_STRATEGY, 
        new AsianLineBreakStrategy());

5.3 生成文件过大

优化方案：

1. 使用字体子集（只嵌入文档实际用到的字符）
2. 压缩图片资源
3. 复用样式对象

java复制PdfFont font = PdfFontFactory.createFont(
    "font.ttf", 
    PdfEncodings.IDENTITY_H, 
    PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED);
font.setSubset(true);

6. 高级技巧：提升排版专业性

6.1 首行缩进的两个字符

专业中文排版要求段落首行缩进两个字符宽度。注意不要用空格实现，而应使用setFirstLineIndent：

java复制Paragraph p = new Paragraph()
    .setFirstLineIndent(24); // 12pt字体 × 2字符

6.2 标点压缩技术

当标点符号连续出现时（如"），可以适当压缩间距：

java复制Text text = new Text("他说："这是一段引用的内容。"")
    .setCharacterSpacing(-0.5f); // 压缩0.5pt

6.3 避头尾的精细控制

通过实现自定义的LineBreakStrategy可以精确控制标点位置：

java复制public class ChineseLineBreakStrategy implements ILineBreakStrategy {
    @Override
    public int getBreakPoint(Text text, float maxWidth) {
        // 实现自定义的换行算法
    }
}

7. 性能优化与批量处理

7.1 内存管理要点

处理大型PDF时：

1. 分批次处理内容
2. 及时关闭文档对象
3. 复用字体等资源

java复制try (PdfDocument pdfDoc = new PdfDocument(new PdfWriter(out))) {
    Document doc = new Document(pdfDoc);
    // 添加内容
} // 自动关闭

7.2 多线程生成策略

安全的多线程方案：

1. 每个线程独立的PdfDocument实例
2. 共享只读资源（如字体）
3. 最终合并PDF

java复制// 使用PDFMergerUtility合并多个PDF
PDFMergerUtility merger = new PDFMergerUtility();
merger.addSource("part1.pdf");
merger.addSource("part2.pdf");
merger.setDestinationFileName("combined.pdf");
merger.mergeDocuments();

8. 实际项目中的经验总结

在银行对账单项目中，我们遇到了超长表格的排版问题。最终解决方案是：

1. 实现自动分页表格
2. 表头每页重复
3. 防止行内分页

java复制Table table = new Table(UnitValue.createPercentArray(4))
    .setKeepTogether(true)
    .setKeepWithNext(true);

// 添加表头
table.addHeaderCell(new Cell().add(new Paragraph("日期")));
// ...

// 设置表头重复
table.setSkipFirstHeader(false);
table.setSkipLastFooter(true);

另一个电商项目中的教训：不同操作系统上字体渲染的差异。最终我们：

1. 统一使用思源字体系列
2. 在CI环境中生成参考PDF
3. 实现视觉回归测试

9. 现代替代方案评估

除了传统PDF库，现代方案还包括：

1. Thymeleaf+PDF：先用HTML模板渲染，再转PDF
2. JasperReports：专业报表工具，内置中文支持
3. Playwright：用浏览器引擎生成PDF

java复制// Playwright示例
try (Playwright playwright = Playwright.create()) {
    Browser browser = playwright.chromium().launch();
    Page page = browser.newPage();
    page.setContent("<html><body><p>中文内容</p></body></html>");
    page.pdf(new Page.PdfOptions()
        .setPath(Paths.get("output.pdf")));
}

10. 测试与验证策略

完善的PDF测试应包括：

1. 内容完整性校验
2. 视觉一致性检查
3. 性能基准测试

推荐工具组合：

• PDFBox的PDFTextStripper提取文本验证
• ImageMagick进行视觉差异检测
• JMeter压力测试生成性能

java复制// 文本内容验证示例
PDFTextStripper stripper = new PDFTextStripper();
String text = stripper.getText(pdfDoc);
assert text.contains("预期内容");

11. 扩展阅读与资源推荐

1. 官方文档：

   • iText官方中文指南（需注意授权条款）
   • PDFBox字体处理专题

2. 开源字体：

   • 思源系列（Adobe与Google合作）
   • 阿里巴巴普惠体

3. 进阶工具：

   • Apache FOP：XSL-FO处理器
   • OpenPDF：iText分支

4. 排版规范：

   • 《中文排版需求》W3C标准
   • 《GB/T 15834-2011》标点符号用法

在实际项目中，我发现最容易被忽视的是文档结构标记（Tagged PDF）。通过正确设置文档结构，可以大幅提升可访问性：

java复制pdfDoc.setTagged();
Paragraph p = new Paragraph("重要内容")
    .setRole(PdfName.H1);