該頁面可以包含自動翻譯的文字。

在 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 上範例程式碼顯示了所有步驟。請看一下範例。