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

在 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.5.17664-dev HTML 转 PDF 插件 9.5.17664-dev
回归测试 14,820 通过 NuGet 总下载量 4,998,853

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

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

该插件可在 NuGet 上以及包含库二进制文件的 zip 包中找到。在下载 C# .NET PDF 库页面上获取库、插件和免费限时许可证密钥。

简单的 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();

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

我们提供示例代码，展示如何使用 API，既可用于同步，也可用于异步控制台应用程序。此外，还有适用于 Windows 窗体和 WPF 应用程序的示例代码。

还有 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 代码，并支持一些变量。这些变量包括 date、title、url、pageNumber 和 totalPages。页眉模板和页脚模板支持同一组变量。

建议对图像使用内联样式和数据 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 覆盖到现有 PDF 示例代码显示了所有步骤。请查看示例。