将 HTML 转换为 PDF（.NET）

概述

本文档说明如何 使用 C# 将 HTML 转换为 PDF。它涵盖以下主题。

以下代码片段同样适用于 Aspose.PDF.Drawing 库。

Aspose.PDF for .NET 是一套 PDF 操作 API，能够无缝将任意现有 HTML 文档转换为 PDF。HTML 转 PDF 的过程可以灵活定制。

将 HTML 转换为 PDF

以下 C# 示例代码展示了如何将 HTML 文档转换为 PDF。

创建 HtmlLoadOptions 类的实例。
初始化 Document 对象。
调用 Document.Save() 方法保存输出的 PDF 文档。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHTMLtoPDF()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    // Load the HTML file into a document using HtmlLoadOptions
    var options = new Aspose.Pdf.HtmlLoadOptions();

    // Open HTML document
    using (var document = new Aspose.Pdf.Document(dataDir + "test.html", options))
    {
        // Save PDF document
        document.Save(dataDir + "ConvertHTMLtoPDF_out.pdf");
    }
}

尝试在线将 HTML 转换为 PDF

Aspose 提供了一个免费在线应用 “HTML to PDF”，您可以在其中试用此功能并查看实际效果。

高级 HTML 转 PDF 转换

HTML 转换引擎提供了多种选项，帮助我们控制转换过程。

媒体查询支持

媒体查询是一种流行技术，用于向不同设备提供定制的样式表。我们可以使用 HtmlMediaType 属性设置设备类型。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHTMLtoPDFAdvancedMediaType()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    // Load the HTML file into a document using HtmlLoadOptions with Print media type
    var options = new HtmlLoadOptions
    {
        // Set Print or Screen mode
        HtmlMediaType = Aspose.Pdf.HtmlMediaType.Print
    };

    // Open HTML document
    using (var document = new Aspose.Pdf.Document(dataDir + "test.html", options))
    {
        // Save PDF document
        document.Save(dataDir + "ConvertHTMLtoPDFAdvancedMediaType_out.pdf");
    }
}

启用（禁用）字体嵌入

HTML 页面常常使用字体（例如本地文件夹中的字体、Google Fonts 等）。我们也可以通过 IsEmbedFonts 属性控制文档中字体的嵌入。

 // For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
 private static void ConvertHTMLtoPDFAdvancedEmbedFonts()
 {
     // The path to the documents directory
     var dataDir = RunExamples.GetDataDir_AsposePdf();

     // Load the HTML file into a document using HtmlLoadOptions with the font embedding option set
     var options = new Aspose.Pdf.HtmlLoadOptions
     {
         // Disable font embedding
         IsEmbedFonts = false
     };

     // Open HTML document
     using (var document = new Aspose.Pdf.Document(dataDir + "test_fonts.html", options))
     {
         // Save PDF document
         document.Save(dataDir + "ConvertHTMLtoPDFAdvanced_EmbedFonts_out.pdf");
     }
 }

管理外部资源加载

转换引擎提供了一种机制，允许您控制与 HTML 文档关联的某些资源的加载。
HtmlLoadOptions 类拥有属性 CustomLoaderOfExternalResources，可用于定义资源加载器的行为。
假设我们需要将所有 PNG 图像替换为单个图像 test.jpg，并将外部 URL 替换为内部资源的 URL。
为此我们可以定义自定义加载器 SamePictureLoader，并将 CustomLoaderOfExternalResources 指向该名称。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHTMLtoPDFAdvanced_DummyImage()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    // Load the HTML file into a document with a custom resource loader for external images
    var options = new Aspose.Pdf.HtmlLoadOptions
    {
        CustomLoaderOfExternalResources = SamePictureLoader
    };

    // Open HTML document
    using (var document = new Aspose.Pdf.Document(dataDir + "test.html", options))
    {
        // Save PDF document
        document.Save(dataDir + "html_test.pdf");
    }
}

private static Aspose.Pdf.LoadOptions.ResourceLoadingResult SamePictureLoader(string resourceURI)
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();
    Aspose.Pdf.LoadOptions.ResourceLoadingResult result;

    if (resourceURI.EndsWith(".png"))
    {
        byte[] resultBytes = File.ReadAllBytes(dataDir + "test.jpg");
        result = new Aspose.Pdf.LoadOptions.ResourceLoadingResult(resultBytes)
        {
            // Set MIME Type
            MIMETypeIfKnown = "image/jpeg"
        };
    }
    else
    {
        result = new Aspose.Pdf.LoadOptions.ResourceLoadingResult(GetContentFromUrl(resourceURI));
    }
    return result;
}

private static byte[] GetContentFromUrl(string url)
{
    var httpClient = new System.Net.Http.HttpClient();
    return httpClient.GetByteArrayAsync(url).GetAwaiter().GetResult();
}

在单页中渲染所有 HTML 内容

Aspose.PDF for .NET 提供了在将 HTML 文件转换为 PDF 格式时将所有内容渲染到单页的能力。例如，当 HTML 内容的输出尺寸超过一页时，您可以使用此选项将输出数据渲染到单个 PDF 页面。为启用此选项，HtmlLoadOptions 类新增了 IsRenderToSinglePage 标志。下面的代码片段展示了如何使用此功能。

 // For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
 private static void ConvertHTMLtoPDFAdvancedSinglePageRendering()
 {
     // The path to the documents directory
     var dataDir = RunExamples.GetDataDir_AsposePdf();

     // Initialize HtmlLoadOptions
     var options = new Aspose.Pdf.HtmlLoadOptions
     {
         // Set Render to single page property
         IsRenderToSinglePage = true
     };

     // Open PDF document
     using (var document = new Aspose.Pdf.Document(dataDir + "HTMLToPDF.html", options))
     {
         // Save PDF document
         document.Save(dataDir + "RenderContentToSamePage_out.pdf");
     }
 }

使用 SVG 数据渲染 HTML

Aspose.PDF for .NET 能够将 HTML 页面转换为 PDF 文档。由于 HTML 允许在页面中以标签形式添加 SVG 图形元素，Aspose.PDF 也支持将此类数据转换为生成的 PDF 文件。以下代码片段展示了如何将包含 SVG 图形标签的 HTML 文件转换为带标签的 PDF 文档。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHTMLtoPDFWithSVG()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    // Initialize HtmlLoadOptions
    var options = new Aspose.Pdf.HtmlLoadOptions(Path.GetDirectoryName(dataDir + "HTMLSVG.html"));

    // Initialize Document object
    using (var document = new Aspose.Pdf.Document(dataDir + "HTMLSVG.html", options))
    {
        // Save PDF document
        document.Save(dataDir + "RenderHTMLwithSVGData_out.pdf");
    }
}

从 HTML 标签创建逻辑结构

为了满足可访问性要求，PDF 文档应包含定义阅读顺序的逻辑结构元素，为屏幕阅读器提供替代文本以描述文档的插图部分，并标记内容层次结构。

许多 HTML 文档已经包含此类逻辑结构。Aspose.PDF 可以在 HTML‑to‑PDF 转换过程中保留并转移这些结构到 PDF。

将 HtmlLoadOptions.CreateLogicalStructure 属性设为 true，即可使用 PDF 逻辑结构元素复制原始 HTML 文档的结构。

输出 PDF 中逻辑结构的质量直接取决于原始 HTML 标记的质量。结构不良或无效的 HTML 可能导致转换后的 PDF 中逻辑结构不完整或不准确。

.NET Core 3.1

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHtmlToPdfWithLogicalStructure()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_WorkingDocuments();

    // Initialize HtmlLoadOptions
    Aspose.Pdf.HtmlLoadOptions options = new Aspose.Pdf.HtmlLoadOptions
    {
        // Convert HTML markup to PDF logical structure elements
        CreateLogicalStructure = true
    };

    // Open PDF document
    using (Aspose.Pdf.Document document = new Aspose.Pdf.Document(dataDir + "HTMLToPDF.html", options))
    {
        // Save PDF document
        document.Save(dataDir + "HtmlToPdfCreateLogicalStructure.pdf");
    }
}

.NET 8

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void AdjustPosition()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf_WorkingDocuments();

    // Initialize HtmlLoadOptions
    Aspose.Pdf.HtmlLoadOptions options = new Aspose.Pdf.HtmlLoadOptions
    {
        // Convert HTML markup to PDF logical structure elements
        CreateLogicalStructure = true
    };

    // Open PDF document
    using Aspose.Pdf.Document document = new Aspose.Pdf.Document(dataDir + "HTMLToPDF.html", options);
        
    // Save PDF document
    document.Save(dataDir + "HtmlToPdfCreateLogicalStructure.pdf");
}

将网页转换为 PDF

将网页转换为 PDF 与转换本地 HTML 文档略有不同。为了将网页内容转换为 PDF 格式，我们可以先使用 HttpClient 实例获取 HTML 页面内容，创建 Stream 对象，将内容传递给 Document 对象并渲染为 PDF。

在将托管于 Web 服务器的网页转换为 PDF 时：

将网页转换为 PDF

使用 HttpClient 对象读取页面内容。
实例化 HtmlLoadOptions 对象并设置基准 URL。
在传入流对象的同时初始化 Document 对象。
（可选）设置页面尺寸和/或方向。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertHTMLtoPDFAdvanced_WebPage()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    const string url = "https://en.wikipedia.org/wiki/Aspose_API";

    // Set page size A3 and Landscape orientation;   
    var options = new Aspose.Pdf.HtmlLoadOptions(url)
    {
        PageInfo =
        {
            Width = 842,
            Height = 1191,
            IsLandscape = true
        }
    };

    // Load the web page content as a stream and create a PDF document
    using (var document = new Aspose.Pdf.Document(GetContentFromUrlAsStream(url), options))
    {
        // Save PDF document
        document.Save(dataDir + "html_test.pdf");
    }
}

private static Stream GetContentFromUrlAsStream(string url, System.Net.ICredentials credentials = null)
{
    using (var handler = new System.Net.Http.HttpClientHandler { Credentials = credentials })
    using (var httpClient = new System.Net.Http.HttpClient(handler))
    {
        return httpClient.GetStreamAsync(url).GetAwaiter().GetResult();
    }
}

为网页转 PDF 提供凭据

有时我们需要转换需要身份验证和访问权限的 HTML 文件，以便只有授权用户才能获取页面内容。这也包括 HTML 中引用的某些资源/数据需要从要求身份验证的外部服务器获取的场景。为满足此需求，ExternalResourcesCredentials 属性已添加到 HtmlLoadOptions 类中。下面的代码片段展示了在将 HTML 文件转换为 PDF 时传递凭据以请求 HTML 及其相应资源的步骤。

 // For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
 private static void ConvertHTMLtoPDFAdvancedAuthorized()
 {
     // The path to the documents directory
     var dataDir = RunExamples.GetDataDir_AsposePdf();

     const string url = "http://httpbin.org/basic-auth/user1/password1";
     var credentials = new System.Net.NetworkCredential("user1", "password1");

     var options = new Aspose.Pdf.HtmlLoadOptions(url)
     {
         ExternalResourcesCredentials = credentials
     };

     using (var document = new Aspose.Pdf.Document(GetContentFromUrlAsStream(url, credentials), options))
     {
         // Save PDF document
         document.Save(dataDir + "HtmlTest_out.pdf");
     }
 }

private static Stream GetContentFromUrlAsStream(string url, System.Net.ICredentials credentials = null)
{
    using (var handler = new System.Net.Http.HttpClientHandler { Credentials = credentials })
    using (var httpClient = new System.Net.Http.HttpClient(handler))
    {
        return httpClient.GetStreamAsync(url).GetAwaiter().GetResult();
    }
}

将 MHTML 转换为 PDF

尝试在线将 MHTML 转换为 PDF

Aspose.PDF for .NET 提供了一个免费在线应用 “MHTML to PDF”，您可以在其中试用此功能并查看实际效果。

MHTML，即 MIME HTML，是一种网页归档格式，用于将通常通过外部链接（如图像、Flash 动画、Java 小程序和音频文件）表示的资源与 HTML 代码合并为单个文件。MHTML 文件的内容被编码为类似 HTML 电子邮件的 MIME 类型 multipart/related。Aspose.PDF for .NET 能将 HTML 文件转换为 PDF 格式，并且在 Aspose.PDF for .NET 9.0.0 版本中，我们引入了将 MHTML 文件转换为 PDF 格式的新功能。下面的代码片段展示了如何使用 C# 将 MHTML 文件转换为 PDF 格式：

将 MHTML 转换为 PDF

创建 MhtLoadOptions 类的实例。
初始化 Document 对象。
调用 Document.Save() 方法保存输出的 PDF 文档。

// For complete examples and data files, visit https://github.com/aspose-pdf/Aspose.PDF-for-.NET
private static void ConvertMHTtoPDF()
{
    // The path to the documents directory
    var dataDir = RunExamples.GetDataDir_AsposePdf();

    // Initialize MhtLoadOptions with page setup
    var options = new Aspose.Pdf.MhtLoadOptions()
    {
        PageInfo = { Width = 842, Height = 1191, IsLandscape = true }
    };

    // Initialize Document object using the MHT file and options
    using (var document = new Aspose.Pdf.Document(dataDir + "fileformatinfo.mht", options))
    {
        // Save PDF document
        document.Save(dataDir + "MhtmlTest_out.pdf");
    }
}

在 .NET 中将 PDF 转换为 PowerPoint 在 .NET 中将 PDF 转换为 HTML