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

HTML 转 PDF 功能

您可以使用 Docotic.Pdf 库将 HTML 转换为 PDF。查看本页提到的资源，了解如何根据您的数据创建精美的 PDF。

您需要 HTML 到 PDF 插件来将 HTML 转换为 PDF。这是 Docotic.Pdf 库的免费附加组件。该附加组件也可在带有库二进制文件的 zip 文件中找到。

Docotic.Pdf 库 9.5.17664-dev HTML 转 PDF 插件 9.5.17664-dev
回归测试 14,820 通过 NuGet 总下载量 4,998,853

API参考

在我们的网站上，我们提供了 HTML 转 PDF 插件的 API 参考。

文章

请阅读以下内容，了解有关 C# 和 VB.NET 代码中的 HTML 到 PDF 转换的更多信息。

在 C# 和 VB.NET 中将 HTML 转换为 PDF
包含 C# HTML 到 PDF 的转换代码，演示如何在 C# 和 VB.NET 中从具有 CSS 样式的 HTML 代码生成 PDF。
在 Azure Functions 中将 HTML 转换为 PDF
如何在 Windows 和 Linux 中使用 .NET Core 在 Azure Functions 和 Azure 应用服务中将 HTML 转换为 PDF。

示例代码

HTML 到 PDF 转换是可以描述各种相关任务的术语。以下部分将更详细地描述这些任务。

HTML 到 PDF C# 转换

您需要先安装该插件。使用包管理器从 NuGet 安装 HTML 到 PDF 插件。

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

该插件提供仅异步的 API。我们将其设计为与异步事件处理程序和异步方法配合使用。您可以在 Windows 窗体、WPF、ASP.NET 和控制台应用程序中使用该插件。

C# HTML 到 PDF 的代码如下：

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("out.pdf");

代码创建了 HTML 到 PDF 转换器的一个实例。然后代码使用该实例从 HTML 创建 PDF。您可以继续使用 PDF 文档，但示例代码只会保存文档。

如果您的控制台应用程序使用旧版本的 C#，并且您没有异步 Main，请不要担心。您仍然可以在您的应用程序中使用该插件。

以下代码显示如何以常规同步方法将 URL 转换为 PDF：

Task.Run(async () =>
{
    using var converter = await HtmlConverter.CreateAsync();
    var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
    using var pdf = await converter.CreatePdfAsync(uri);
    pdf.Save("out.pdf");
}).GetAwaiter().GetResult();

VB.NET 应用程序使用类似的代码。以下是一段代码，展示了如何在 VB.NET 中将 HTML 转换为 PDF。

Task.Run(
    Async Function()
        Using converter = Await HtmlConverter.CreateAsync()
            Dim uri = New Uri("https://bitmiracle.com/pdf-library/html-pdf/")
            Using pdf = Await converter.CreatePdfAsync(uri)
                pdf.Save("out.pdf")
            End Using
        End Using
    End Function
).GetAwaiter().GetResult()

从我们的 GitHub 存储库下载完整的测试项目：

在 C# 中将 HTML 字符串转换为 PDF

常见任务之一是在 C# 或 VB.NET 应用程序中从 HTML 生成 PDF。该过程可能从应用程序使用数据库中的数据填充的模板开始。网站用户创建模板、数据或两者并不少见。

自动生成或上传的 HTML 可以采用文件或带有代码的字符串的形式。该插件提供了一种方法接受文件路径。使用该方法在 C# 代码中将 HTML 文件转换为 PDF。以下代码适用于您有字符串的情况。

using var converter = await HtmlConverter.CreateAsync();

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

HTML 可以包含对图像、脚本和 CSS 文件的相对引用。要正确转换此类代码，您需要使用转换选项。以下是使用选项指定基本 URL 的方法：

using var converter = await HtmlConverter.CreateAsync();

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("out.pdf");

我们的 GitHub 存储库包含完整的测试项目。

转换前执行 JavaScript

插件 API 提供了一种在转换之前运行 JS 代码的方法。该代码可以动态生成或修改 HTML 内容。例如，它可以切换元素，或实现动态内容加载。

以下代码显示如何延迟 HTML 到 PDF 的转换，直到 JavaScript 完成。

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
var js = @"document.body.style.backgroundColor = 'green';";
options.Start.SetStartAfterScriptRun(js);

var url = new Uri("https://google.com");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

上面的代码片段使用了一个非常简单的代码来说明该方法。有关更真实的例子，请查看我们 GitHub 存储库中的相应的示例应用程序。该应用程序展示了如何处理动态加载其内容的页面。应用程序中的 JavaScript 代码会滚动页面，直到没有新内容。之后，将转换为 PDF。

忽略 SSL 错误

在发送安全请求加载 HTML 时，该插件会检查验证网站身份并启用加密连接的 SSL 证书是否有效且可信。

默认情况下，如果 HTML 到 PDF 转换器因任何原因不信任证书，该插件将抛出异常。如果您了解接受不受信任的证书的风险，您可以告诉该插件绕过检查。

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("out.pdf");

有关完整代码，请前往 Docotic.Pdf 示例 repo。

为受保护的页面提供密码

某些网页需要身份验证才能访问。当您访问需要 HTTP 身份验证的安全 URL 时，浏览器会要求您提供用户名和密码。

使用转换选项，您可以指示 API 为需要登录的网页提供凭据。

此 C# 代码显示如何将受密码保护的 HTML 转换为 PDF

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://httpbin.org/basic-auth/foo/bar");

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

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

在示例仓库中查找完整工作示例。

转换前等待

如果页面在加载后持续更新一段时间，则延迟 HTML 到 PDF 的转换会很有用。处理 JavaScript 或 AJAX 调用生成的动态内容时通常会出现这种情况。

Acid 3 测试是转换前延迟效果较好的页面的完美示例。该测试执行多次检查，以评估浏览器正确呈现复杂网页的能力。这些检查需要时间。尝试更改以下代码中的等待时间，看看它如何影响转换结果。

var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://acid3.acidtests.org/");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

上述代码显示了如何使用延迟将 HTML 转换为 PDF。虽然额外的时间有助于获得更好的结果，但请注意，添加延迟会影响性能。延迟不足会对转换质量产生负面影响。使用延迟的另一种方法是使用脚本，该脚本将一直执行到页面准备就绪为止。

您可以在 Docotic.Pdf 示例库中获取完整测试项目。

添加页眉和页脚

HTML 转 PDF API 可以在生成的页面上添加可重复的页脚/页眉块。转换器根据转换选项中指定的 HTML 模板创建块。我们建议在模板内对图像使用内联样式和数据 URI。

转换器将页眉和页脚放在页边距内。由于页边距较小，页眉和页脚的内容可能不可见。我们建议明确指定顶部和底部边距。大小应分别与页眉和页脚的大小匹配。

了解如何将 HTML 转换为 PDF 并添加页眉和页脚

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.HeaderTemplate = File.ReadAllText("header-template.html");
options.Page.MarginTop = 50;

options.Page.FooterTemplate = File.ReadAllText("footer-template.html");
options.Page.MarginBottom = 50;

var url = new Uri("https://www.iana.org/numbers");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

转换器可以在模板内预定义的位置插入转换日期和文档标题等值。查看 HeaderTemplate 和 FooterTemplate 属性的描述以了解更多信息。

完整的测试项目和模板代码位于 Docotic.Pdf 示例库中。

量表内容

处理布局较宽的网页时，您可以增加输出 PDF 大小或缩小内容以适合 PDF 页面。为了更好地定位缩放后的内容，您还可以设置边距。

缩放比例合适的 PDF 可提供更好的阅读体验，因为读者无需放大或缩小即可正确查看内容。如果 HTML 文档因字体较小而难以阅读，您可以放大内容。

默认情况下，API 生成的 PDF 页面大小为 A4。没有边距，也没有放大率。使用转换选项，您可以更改这些设置。

了解如何在从 HTML 生成 PDF 时设置缩放比例和边距

using var converter = await HtmlConverter.CreateAsync();

var html = "<html><head><style>body { background-color: coral; margin-top: 100px;}</style></head>" +
"<body><h1>Did you notice the margins and the scale?</h1></body></html>";

var options = new HtmlConversionOptions();
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.CreatePdfFromStringAsync(html, options);
pdf.Save("out.pdf");

Docotic.Pdf 示例库包含完整项目。

将 HTML 叠加到现有 PDF 上

有时您可能想使用现有 PDF 作为转换结果的背景。使用 Docotic.Pdf 和附加组件即可实现。

此方法涉及从 HTML（覆盖内容）创建新的 PDF，然后将其与现有 PDF 合并。最终文档将包含原始内容和新覆盖。以下是说明该方法的代码。

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.SetSizeInches(4.13, 5.83);

string htmlCode =
    "<div style=\"position: absolute; top: 270px; right: 100px;\">" +
    "I would like to put this here</div>";
using var htmlPdf = await converter.CreatePdfFromStringAsync(htmlCode, options);

using var pdf = new PdfDocument("pdf-to-merge-with.pdf");
var xObj = pdf.CreateXObject(htmlPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("out.pdf");

指定覆盖的页面大小很重要。通常，大小应等于您要覆盖的页面的大小。然后您需要生成包含覆盖内容的新 PDF。请注意，背景默认是透明的。如果需要，您可以通过在转换前运行脚本来更改背景。

现在该打开现有的 PDF 了。此文档应从生成的 PDF 中的页面创建一个 XObject。然后代码在现有页面的顶部绘制 XObject。

完整的带有示例源 PDF 的测试项目位于 Docotic.Pdf 示例存储库中。

在 C# 中将 SVG 转换为 PDF

使用 HTML 到 PDF 转换器从带有可缩放矢量图形的图像创建 PDF。以下代码显示了执行转换的最简单方法：

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/team.svg");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("out.pdf");

转换器使用 SVG 图像中指定的宽度和/或高度来生成正确尺寸的高质量输出。

您可以生成使用自定义选项的不同尺寸的输出。可以将转换后的图像添加到另一个 PDF。

在 GitHub 上查看完整测试项目。