摘要： 跨平台 PDF 生成的新选择：xPlat.OpenPDF 深度解析 在 .NET 生态系统中，PDF 的生成一直是一个充满挑战的领域。开发者往往在“昂贵的商业库”与“难以维护的开源...

跨平台 PDF 生成的新选择：xPlat.OpenPDF 深度解析

在 .NET 生态系统中，PDF 的生成一直是一个充满挑战的领域。开发者往往在“昂贵的商业库”与“难以维护的开源库”之间徘徊。许多经典的 PDF 库依赖于特定的 Windows GDI+ 图形库，导致在 Linux 容器或 macOS 上运行时频繁出现 System.Drawing 相关的崩溃。

xPlat.OpenPDF 的出现为我们提供了一种优雅的解决方案。它通过将成熟的 Java OpenPDF 库（iText 2.1.7 的分支）移植或桥接至 .NET 跨平台环境，旨在提供一个无需依赖特定操作系统图形库、高性能且完全开源的 PDF 创建方案。

1. 为什么选择 xPlat.OpenPDF？

摆脱 GDI+ 依赖

大多数 .NET PDF 库在处理字体和布局时依赖 System.Drawing.Common。在 .NET 6 及更高版本中，微软宣布 System.Drawing.Common 在非 Windows 平台上不再受支持。xPlat.OpenPDF 采用了跨平台的设计架构，确保你的代码在 Windows、Linux (Docker) 和 macOS 上表现一致。

成熟的血统

OpenPDF 是 iText 2.1.7 的一个活跃分支。这意味着它继承了 iText 强大的文档对象模型（DOM）处理能力，支持复杂的表格、页眉页脚、分级标题以及精确的坐标定位，同时避开了 iText ⁵⁄₇ 复杂的 AGPL 商业授权限制。

轻量级与高性能

相比于通过 HTML-to-PDF 转换（如 Puppeteer 或 wkhtmltopdf）这种需要启动整个浏览器内核的方案，xPlat.OpenPDF 直接操作 PDF 语法，内存占用极低，生成速度极快。

2. 快速上手实例

为了让你快速理解如何使用 xPlat.OpenPDF，下面我们将构建一个简单的示例：创建一个包含标题、段落和表格的 PDF 文档。

安装 NuGet 包

首先，在你的项目中添加引用：

dotnet add package xPlat.OpenPDF

基础代码实现

using System;
using System.IO;
using xPlat.OpenPDF; // 假设命名空间定义
using com.lowagie.text;
using com.lowagie.text.pdf;

public class PdfGenerator
{
    public void CreateSamplePdf(string outputPath)
    {
        // 1. 创建文档对象
        Document document = new Document(PageSize.A4);

        try
        {
            // 2. 创建 PdfWriter 将文档写入文件流
            PdfWriter writer = PdfWriter.GetInstance(document, new FileStream(outputPath, FileMode.Create));

            // 3. 打开文档准备写入
            document.Open();

            // --- 添加标题 ---
            Font titleFont = FontFactory.GetFont(FontFactory.HELVETICA_BOLD, 18);
            Paragraph title = new Paragraph("xPlat.OpenPDF 跨平台演示报告", titleFont);
            title.Alignment = Element.ALIGN_CENTER;
            document.Add(title);

            // 添加空行
            document.Add(new Paragraph("\n"));

            // --- 添加正文 ---
            Font bodyFont = FontFactory.GetFont(FontFactory.HELVETICA, 12);
            document.Add(new Paragraph("这是一个使用 xPlat.OpenPDF 生成的文档。它不需要依赖 Windows GDI+，因此可以在 Docker 容器中完美运行。", bodyFont));
            document.Add(new Paragraph("以下是生成的动态数据表格：", bodyFont));
            document.Add(new Paragraph("\n"));

            // --- 添加表格 ---
            // 创建一个 3列 4行的表格
            PdfPTable table = new PdfPTable(3);
            table.WidthPercentage = 100;

            // 添加表头
            table.AddCell(new PdfPCell(new Phrase("项目名称", titleFont)));
            table.AddCell(new PdfPCell(new Phrase("版本", titleFont)));
            table.AddCell(new PdfPCell(new Phrase("状态", titleFont)));

            // 添加数据行
            string[][] data = {
                new[] { "xPlat.OpenPDF", "1.0.0", "稳定" },
                new[] { ".NET 8", "Current", "活跃" },
                new[] { "Linux Docker", "Latest", "兼容" }
            };

            foreach (var row in data)
            {
                foreach (var cellText in row)
                {
                    table.AddCell(new PdfPCell(new Phrase(cellText, bodyFont)));
                }
            }

            document.Add(table);

            // 4. 关闭文档
            document.Close();
            Console.WriteLine($"PDF 已成功生成至: {outputPath}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"生成 PDF 出错: {ex.Message}");
        }
    }
}

3. 核心功能进阶

3.1 处理中文字体（关键点）

PDF 默认仅支持标准 14 种字体（如 Helvetica, Times）。要显示中文，必须加载外部 .ttf 字体文件。

// 加载中文字体
string fontPath = "fonts/msyh.ttf"; // 微软雅黑路径
BaseFont bf = BaseFont.CreateFont(fontPath, BaseFont.IDENTITY_H, BaseFont.EMBEDDED);
Font chineseFont = new Font(bf, 12);

document.Add(new Paragraph("你好，世界！这是中文支持测试。", chineseFont));

3.2 精确坐标定位 (Absolute Positioning)

如果你需要制作发票或证书，需要将元素放在页面的特定位置，可以使用 PdfContentByte。

PdfContentByte cb = writer.GetDirectContent();
cb.BeginText();
cb.SetFontAndSize(titleFont, 12);
cb.ShowTextAligned(PdfContentByte.ALIGN_LEFT, "页脚水印: 机密文档", 50, 50, 0);
cb.EndText();

3.3 页面事件处理 (页码与页眉)

通过实现 PdfPageEventHelper，你可以为每一页自动添加页码。

public class PageEvent : PdfPageEventHelper
{
    public override void OnEndPage(PdfWriter writer, Document document)
    {
        var cb = writer.DirectContent;
        string text = $"第 {writer.PageNumber} 页";
        cb.BeginText();
        cb.ShowTextAligned(PdfContentByte.ALIGN_CENTER, text, 297, 20, 0);
        cb.EndText();
    }
}

// 在 writer 创建后绑定
writer.SetPageEvent(new PageEvent());

4. 性能对比与适用场景

推荐使用场景：

• 自动化报告：需要快速生成大量结构化报表。
• 云原生应用：部署在 Kubernetes/Docker 的微服务，对内存敏感。
• 简单发票/凭证：对布局有固定要求，不需要复杂 CSS 样式。
• 预算有限的项目：需要商业级稳定性但无法支付高额授权费。

5. 总结

xPlat.OpenPDF 将 Java 世界中极其稳定的 OpenPDF 能力带到了 .NET 平台，解决了长期以来困扰开发者的 System.Drawing 跨平台兼容性痛点。虽然它不像 HTML 转换那样可以通过 CSS 快速美化，但其在执行效率、资源消耗和稳定性方面的优势使其成为企业级后端 PDF 生成的理想选择。

如果你正在寻找一个轻量、免费且能在 Linux 上稳定运行的 PDF 库，xPlat.OpenPDF 绝对值得尝试。