為什麼需要C#將HTML轉PDF？
在企業專案、報表自動化、電子發票、合約生成等場景中，常需將動態HTML內容轉為PDF格式，方便列印、存檔或傳遞。舉例來說，許多ERP或CRM系統會根據資料動態產生報表，最終需以PDF形式匯出給客戶或內部審核。此外，電子簽核、批次文件歸檔等流程，也高度依賴HTML轉PDF的自動化能力。
主流C# HTML轉PDF方案比較
| 工具名稱 | 優點 | 缺點與限制 | 適用情境 |
|---|---|---|---|
| DinkToPdf | 開源、支援CSS/JS、易於整合、社群資源多 | 跨平台需額外設定、對新CSS支援有限 | 報表、發票、一般文件自動化 |
| HtmlRenderer.PdfSharp | 輕量、易於安裝、無外部依賴 | CSS/JS支援有限、複雜排版困難 | 簡單靜態內容、內部報表 |
| SelectPdf | 功能完整、支援高級CSS/JS、商用授權 | 收費、學習曲線較高 | 企業級應用、複雜排版、需專業支援 |
| pdfFiller | 雲端API、無需自行維護、支援多格式轉換 | 需網路連線、API收費 | 雲端自動化、批次轉檔、跨平台 |
| SignNow | 強調電子簽核、PDF處理整合、API支援 | 主要聚焦簽核流程、非純轉檔工具 | 合約、簽核文件自動產生 |
本教學以DinkToPdf為例，因其開源、易於上手且適合大多數專案需求。若需雲端批次處理或高度自動化，也可考慮pdfFiller等API服務。
DinkToPdf快速入門
安裝與環境需求
DinkToPdf基於wkhtmltopdf，需搭配原生dll。建議步驟如下：
- 安裝NuGet套件
在Visual Studio的「套件管理器主控台」輸入：
Install-Package DinkToPdf - 下載原生庫
根據作業系統（Windows/Linux），需下載對應的wkhtmltopdf原生檔案，並將dll放置於專案可執行檔目錄下。 - Windows：
libwkhtmltox.dll -
Linux：
libwkhtmltox.so -
常見安裝錯誤排解
- 若出現「找不到wkhtmltox」錯誤，請確認dll路徑正確。
- 若遇到權限問題，請以管理員身分執行或調整目錄權限。
- 建議於開發與部署環境皆測試dll載入狀況。
基本範例與程式碼說明
以下為將HTML字串轉為PDF的完整範例，並附註解說明：
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
// 初始化轉換器
var converter = new SynchronizedConverter(new PdfTools());
// 設定PDF轉換規則
var document = new HtmlToPdfDocument()
{
GlobalSettings = {
PaperSize = PaperKind.A4, // 紙張大小
Orientation = Orientation.Portrait, // 直式
Margins = new MarginSettings { Top = 10, Bottom = 10, Left = 10, Right = 10 }
},
Objects = {
new ObjectSettings
{
HtmlContent = @"
<html>
<head>
<meta charset='utf-8'>
<title>HTML轉PDF範例</title>
</head>
<body>
<h1>這是一個測試</h1>
<p>這是一些示範文字。</p>
</body>
</html>"
}
}
};
// 轉換並儲存PDF
byte[] pdf = converter.Convert(document);
File.WriteAllBytes("output.pdf", pdf);
重點說明：
– HtmlContent可直接放入HTML字串，需注意字元編碼。
– GlobalSettings可調整紙張、方向、邊距等。
– 若需載入外部資源（如圖片、CSS），建議使用絕對路徑或URL。
生成PDF步驟詳解
- 初始化轉換器：建立
SynchronizedConverter物件，確保執行緒安全。 - 設定轉換規則：建立
HtmlToPdfDocument，可自訂多個物件（Objects）分頁。 - 執行轉換：呼叫
Convert方法產生PDF位元組陣列。 - 檔案輸出：使用
File.WriteAllBytes將PDF寫入指定路徑。
常見錯誤：
– 若PDF內容為空，請檢查HTML內容是否正確、資源路徑是否可存取。
– 若遇到「中文亂碼」，請確認HTML有正確宣告<meta charset='utf-8'>，並於系統安裝所需中文字型。
進階應用與常見需求
使用外部HTML文件
若HTML內容存於檔案或網頁，可指定路徑：
new ObjectSettings
{
Page = @"C:\path\to\your\file.html" // 本地檔案
// 或
// Page = "https://yourdomain.com/template.html" // 線上HTML
}
注意事項：
– 本地檔案需確保路徑正確，且資源（如圖片、CSS）同樣可被存取。
– 線上HTML建議使用公開URL，避免權限問題。
添加頁眉、頁腳與頁碼
DinkToPdf支援以HTML自訂頁眉、頁腳，並可插入動態頁碼：
new ObjectSettings
{
HtmlContent = "<p>主要內容</p>",
HeaderSettings = {
HtmlUrl = @"C:\path\to\header.html", // 頁眉HTML
Line = true // 顯示分隔線
},
FooterSettings = {
HtmlContent = "第 [page] 頁，共 [toPage] 頁", // 動態頁碼
Line = true
}
}
補充說明：
– Header/Footer可用HTML設計，支援簡單CSS。
– 動態變數如[page]、[toPage]自動帶入頁碼。
嵌入圖片、字型與處理中文
- 圖片嵌入：建議使用絕對路徑或網路URL，避免相對路徑失效。
- 字型設定：若PDF需顯示特殊字型或中文，請於系統安裝所需字型，或於HTML內以
@font-face指定字型檔案。 - 中文亂碼解決：確保HTML有
<meta charset='utf-8'>，並於PDF產生伺服器安裝中文字型（如微軟正黑體、思源黑體等）。
批次轉檔與大檔案處理
- 若需批次產生多份PDF，建議每次產生後釋放資源，避免記憶體累積。
- 大型HTML轉檔時，建議分批處理、監控記憶體用量，並適時重啟轉換器。
- 若遇到效能瓶頸，可考慮將轉換流程分散至多台機器或使用雲端API（如pdfFiller）。
常見問題與錯誤排解（FAQ）
Q1：安裝後執行出現「找不到wkhtmltox」？
A：請確認已將原生dll放置於可執行檔目錄，且與系統位元數（x86/x64）一致。
Q2：PDF內容為空白或顯示不正確？
A：檢查HTML內容是否正確、資源路徑是否可存取，並確認CSS/JS是否支援。
Q3：中文或特殊字元顯示亂碼？
A：請於HTML加上<meta charset='utf-8'>，並於系統安裝對應字型。
Q4：如何嵌入本地圖片或CSS？
A：請使用絕對路徑或URL，並確認檔案權限與路徑正確。
Q5：Linux環境產生PDF失敗？
A：請下載對應Linux版本的wkhtmltopdf原生檔案，並確保執行權限。
DinkToPdf的限制與替代方案
雖然DinkToPdf適用於多數專案，但仍有以下限制：
- 對新CSS標準、複雜JS支援有限，部分互動式網頁可能無法完整轉換。
- 跨平台部署需自行處理原生庫安裝，維護成本較高。
- 大量高併發轉檔時，效能與穩定性需特別留意。
替代工具建議：
– 若需雲端API、批次處理或更高級的PDF功能，可考慮 pdfFiller （支援多格式轉換、雲端整合）、 SignNow （適合電子簽核與文件流程自動化）。
– 企業級應用或需專業支援時，亦可評估SelectPdf等商用解決方案。
結語與工具推薦
C#結合DinkToPdf能高效將HTML內容轉為PDF，適用於報表、發票、合約等多種自動化場景。若遇到複雜排版、雲端自動化或需電子簽核，亦可評估如pdfFiller、SignNow等API工具，根據專案需求選擇最合適方案，提升團隊產能與文件處理效率。
