该页面可以包含自动翻译的文本。

在 C# 和 VB.NET 中将 HTML 转换为 PDF

如果您已经花费了大量时间和金钱来创建 HTML 形式的内容,您可能希望从该 HTML 创建 PDF。 对于每个想要避 免重复工作的人来说,这种方法是一个自然的方向。

为了成功地重用投资,应以编程方式执行转换,并且生成的 PDF 在视觉上应尽可能接近源 HTML。

HTML 到 PDF 转换

.NET 应用程序中用于 HTML 到 PDF 转换的 API

Docotic.Pdf 库的免费 HTML 到 PDF 附加组件提供了用于此类转换的 API。 该插件和库都可以在为 .NET 和 .NET Core 框架构建的 Web 和桌面应用程序中使用。

Docotic.Pdf 库 9.3.16887-dev HTML 转 PDF 插件 9.3.16887-dev
回归测试 14,635 通过 NuGet 总下载量 4,075,269

该插件是一个 HTML 到 PDF .NET 库,在转换过程中使用 Chromium。 每次转换之前,该插件都会自动检查是否 已下载最新支持的 Chromium。 任何已下载的合格版本都将被重复使用。 如果未找到符合条件的版本,该附加组 件会在转换之前下载一个版本。 预计它将具有与 Google Chrome (R) 相同的网络标准合规性。

该插件可以在 Windows、macOS 和 Linux 环境中从 HTML 生成 PDF。 请阅读关于 Azure 中的 HTML 到 PDF 转 换 一文,了解如何在 Linux 中配置该加载项。

该附加组件在 NuGet 上可用,并且也包含在库的带有二进制文件的 zip 中。 要尝试不受评估模式限制的库,您可以在此处 获取免费的限时许可证密钥。

简单的 HTML 到 PDF C# 转换

使用 HTML 到 PDF API,C# 转换代码可 能如下所示:

static async Task convertUrlToPdfAsync(string urlString, string pdfFileName)
{
    using (var converter = await HtmlConverter.CreateAsync())
    {
        using (var pdf = await converter.CreatePdfAsync(new Uri(urlString)))
            pdf.Save(pdfFileName);
    }
}

这相当简单。 只需两次调用即可生成 PDF 文档。 正如您所看到的,该 API 是异步的,根本不提供同步方法。

如果您想从某些同步代码调用 API,可以使用以下包装器:

Task.Run(async () =>
{
    await convertUrlToPdfAsync("https://bitmiracle.com/", "output.pdf");
}).GetAwaiter().GetResult();

请注意,通常不建议同步调用异步方法,因此仅在别无选择时才使用包装器。

我们提供示例代码,展示如何从同步和异步 console 应用程序使用 API。 此外,还 有 Windows FormsWPF 应用程序的示例代码。

还有 HTML 到 PDF 示例组。 每个示例都有 C# 和 VB.NET 版本。

使用 C# 和 VB.NET 中的 HTML 字符串或文件创建 PDF

使用 API 可以轻松地将 HTML 字符串转换为 PDF。 该字符串可以包含完整的 HTML 文档或仅包含一个片段。 转 换器将为您从 HTML 代码创建 PDF。

var html = "<body><br/><br/><br/><h1>Hello, World<h1></body>";
using (var pdf = await converter.CreatePdfFromStringAsync(html))
    pdf.Save("output.pdf");

您可以为要转换的 HTML 代码中的所有相对链接指定基本 URL。 以下代码片段介绍了如何使用 C# 中的基本 URL 将 HTML 转换为 PDF。

var incompleteHtml = "<img src=\"/images/team.svg\"></img>";
var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("https://bitmiracle.com/");
using (var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options))
    pdf.Save("output.pdf");

转换 HTML 文件与转换 URL 几乎相同。 只需使用接受路径而不是 URL 的CreatePdfAsync重载即可。 使用 C# 或 VB.NET 代码将 HTML 文件转换为 PDF 时,还支持基本 URL 和其他选项。

var sampleHtmlPath = @"C:\path\to\sample.html";
using (var pdf = await converter.CreatePdfAsync(sampleHtmlPath))
    pdf.Save("output.pdf");

您还可以使用 API 将 SVG 图像转换为 PDF

使用自定义页面大小、边距和比例

您可以通过为 PDF 创建方法提供转换选项来设置任何 HTML 到 PDF C# 转换。

以下代码片段展示了如何在 C# 中配置输出页面大小、边距和比例:

using (var converter = await HtmlConverter.CreateAsync())
{
    var options = new HtmlConversionOptions();

    // 您还可以指定页面方向是否为横向,并且可以提供以磅或英寸为单位的尺寸
    options.Page.SetSize(PdfPaperSize.ItalyEnvelope);

    options.Page.MarginLeft = 10;
    options.Page.MarginTop = 20;
    options.Page.MarginRight = 30;
    options.Page.MarginBottom = 40;

    options.Page.Scale = 1.5;

    using (var pdf = await converter.CreatePdfAsync(url, options))
        pdf.Save("output.pdf");
}

您可以使用页面选项指定页眉和页脚模板。 这些模板使用常规 HTML 代码并支持一些变量。 这些变量是 datetitleurlpageNumbertotalPages

建议对图像使用内联样式和数据 URI。

您可能想要指定页面的顶部和底部边距。 如果没有边距,页眉或页脚可能会被页面内容遮挡。

在 C# 或 VB.NET 中将 HTML 转换为带有页眉和页脚的 PDF 示例代码演 示了如何在模板中使用变量和数据 URI。

受密码保护的 HTML 到 PDF C# 转换

即使 HTML 页面受用户名/密码对保护,您也可以创建 PDF。 就像在HtmlConversionOptions中设置身份验证选 项一样简单。

var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");

using (var pdf = await converter.CreatePdfAsync(url, options))
    pdf.Save("output.pdf");

如果页面需要设置一些 cookie 才能正常运行,这也很容易。 只需将这些 cookie 添加到选项中即可。 具体方法如下:

var options = new HtmlConversionOptions();
options.Cookies.Add(new Cookie("sessionID", "my-session-ID"));

using (var pdf = await converter.CreatePdfAsync(url, options))
    pdf.Save("output.pdf");

延时转换启动

默认情况下,加载后立即开始转换。 但在某些情况下,页面需要一些时间来稳定。 例如,当它执行一些计算并 在这些计算准备好后更新内容时。

使用转换开始选项,您可以将转换延迟指定的毫秒数。

// 等待 10 秒钟,然后开始转换。
var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);

有时需要运行脚本来切换已加载页面上的元素,或进行动态内容加载。 这也是可能的:

var options = new HtmlConversionOptions();
var js = @"
    async function scrollDownUntilYouCantAnyMore() {
        await new Promise((resolve, reject) => {
            // 为简洁起见省略
            }, 400);
        });
    }
    scrollDownUntilYouCantAnyMore();
";
options.Start.SetStartAfterScriptRun(js);
using (var pdf = await converter.CreatePdfAsync(url, options))
    pdf.Save("output.pdf");

在 C# 或 VB.NET 中运行脚本后将 HTML 转换为 PDF 示例代码包含完整的 scrollDownUntilYouCantAnyMore 函数。 该示例演示了如何在 HTML 到 PDF 转换之前执行脚本。

在 .NET 中将 HTML 转换为 PDF,忽略 SSL 错误

在转换过程中,可能会发生 SSL 错误。 此类错误通常是由于自签名或其他不受信任的证书而发生的。 吊销和过 期的证书也可能导致 HTML 到 PDF 转换器抛出异常。

如果您了解 SSL 错误发生的原因并且确定忽略它们是安全的,则可以忽略它们。 要在 HTML 到 PDF 转换期间忽 略 SSL 错误,请使用带有IgnoreSslErrors = true引擎选 项

var engineOptions = new HtmlEngineOptions
{
    IgnoreSslErrors = true
};
using (var converter = await HtmlConverter.CreateAsync(engineOptions))
{
    var url = new Uri("https://self-signed.badssl.com/");
    using (var pdf = await converter.CreatePdfAsync(url))
        pdf.Save("output.pdf");
}

将 HTML 内容放在 PDF 页面上

在某些情况下,您可能需要转换 HTML 并将转换结果放在某些现有 PDF 页面之上。 例如,当您有一张表单的图 片时,您可能希望在该图片的空白区域上放置一些内容。 结果看起来像一个填写好的表格。

要将转换后的 HTML 覆盖现有 PDF 内容,您需要:

  • 从 HTML 创建具有透明背景的 PDF 页面
  • 从转换后的页面创建 XObject
  • 在现有 PDF 页面上绘制这些 XObject。

转换 HTML 并将其放在 C# 或 VB.NET 中的现有 PDF 内容上 示例代码显示了所有步 骤。 请看一下示例。