「TheArtOfDev.HtmlRenderer.PdfSharp」的踩雷歷程

TLDR

• 若遇到 PdfGenerator.GeneratePdf 執行錯誤，請將 PDFsharp 版本降級至 1.32.3057。
• 若專案編譯失敗，請檢查並移除舊版 NuGet 還原設定（NuGet.targets）。
• 中文顯示異常時，請在 CSS 中明確指定 font-family 為「標楷體」或「DFKai-SB」（視作業系統環境而定）。
• 巢狀表格框線被截斷時，可透過在表格內新增一個高度極小的 <tr> 並微調 height 屬性來修正。

套件初始化與版本衝突

在 .NET Framework 專案中使用 TheArtOfDev.HtmlRenderer.PdfSharp 時，若直接執行範例程式碼，可能會遇到執行時期錯誤。

什麼情況下會遇到這個問題： 初次安裝套件並執行 PdfGenerator.GeneratePdf 方法時。

解決方案：

1. 降級相依套件：將 PDFsharp 版本降級至 1.32.3057。
2. 清理 NuGet 設定：若專案檔（.csproj）中包含舊版的 NuGet.targets 引用，請將其移除，否則會導致編譯失敗。

// 成功執行範例
PdfDocument pdf = PdfGenerator.GeneratePdf("<p><h1>Hello World</h1>This is html rendered text</p>", PageSize.A4);
pdf.Save("document.pdf");

中文字型顯示異常

預設情況下，該套件對中文字元的支援度有限，若未指定字型，中文將無法正確渲染。

什麼情況下會遇到這個問題： 在 HTML 內容中包含中文字元，且未設定 CSS 字型屬性時。

解決方案： 在 HTML 的 <style> 區塊中強制指定 font-family。

string html = @"
    <style>
        * {
            font-family: 標楷體;
        }
    </style>
    <p>中文</p>
";

TIP

• 在 Windows 中文環境下請使用「標楷體」，英文環境下請改用「DFKai-SB」。
• 目前測試僅「標楷體」與「Malgun Gothic」能穩定顯示中文。

表格框線被截斷

當使用巢狀表格（Nested Table）且內部 <td> 設定了固定的 height 屬性時，容易發生底部框線被截斷的問題。

什麼情況下會遇到這個問題： 當巢狀表格的 <td> 元素高度計算不精確，導致內容溢出或邊框渲染範圍錯誤時。

解決方案： 目前無直接修復參數，建議採取「補丁」策略：在表格末尾手動加入一個高度極小的 <tr>，並透過微調 height 屬性（以 0.5px 為單位）來校正框線位置。

<!-- 範例：透過額外 tr 修正框線 -->
<table>
    <tr>
        <td>
            <table class="list">
                <tr><td>內容</td></tr>
                <!-- 額外增加的 tr 用於校正高度 -->
                <tr>
                    <td colspan="3" style="height: 9px;"></td>
                </tr>
            </table>
        </td>
    </tr>
</table>

使用心得

TheArtOfDev.HtmlRenderer.PdfSharp 對 CSS 的支援度較 iTextSharp 更為完整，許多在 iTextSharp 無法生效的樣式在此套件中會正常運作，這可能導致原本的排版需要重新調整。但在處理非標準 HTML 結構（如在 <td> 中放置 <hr />）時，其渲染結果可能與現代瀏覽器（如 Chrome）存在差異，建議在開發時針對複雜排版進行多次測試。

異動歷程

• 2023-12-05 初版文件建立。