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

TLDR

• 若遇到 NuGet 還原錯誤，請檢查並移除專案檔中過時的 NuGet.targets 匯入設定。
• 若發生執行期錯誤，請將 PDFsharp 套件版本降級至 1.32.3057。
• 中文無法顯示時，需在 CSS 中強制指定 font-family 為「標楷體」或「DFKai-SB」（視作業系統語系而定）。
• 巢狀表格框線被截斷時，可透過手動增加額外的 <tr> 並微調 height 屬性（以 0.5px 為單位）來修正顯示異常。

---

NuGet 還原錯誤與版本相容性

什麼情況下會遇到這個問題： 在 .NET Framework 專案中初次安裝或執行 TheArtOfDev.HtmlRenderer.PdfSharp 時。

若在執行時發生 Exception，且專案檔中包含舊版的 NuGet 還原設定，建議執行以下步驟：

1. 移除專案檔 (.csproj) 中關於 NuGet.targets 的匯入設定：

   <Import Project="$(SolutionDir)\.nuget\NuGet.targets" Condition="Exists('$(SolutionDir)\.nuget\NuGet.targets')" />
   <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
       ...
   </Target>

2. 將相依的 PDFsharp 套件版本降級至 1.32.3057，即可解決大部分的初始化錯誤。

---

中文字型顯示異常

什麼情況下會遇到這個問題： 在 PDF 中輸出中文字元時，預設字型無法正確渲染。

解決方法是在 HTML 的 CSS 中明確指定字型。

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

TIP

• 目前預設字型中，僅有「標楷體」和「Malgun Gothic」能夠正確顯示中文。
• 在 Windows 英文環境中，請將「標楷體」更改為「DFKai-SB」。反之，在中文環境中請勿使用「DFKai-SB」。

---

表格框線被截斷

什麼情況下會遇到這個問題： 使用巢狀 <table> 且內部 <td> 設有固定 height 屬性時，容易導致底部或頂部框線被截斷。

針對此問題，目前並無完美的自動化解法，建議採取手動補償的方式：

1. 在表格末端增加一個空的 <tr>。
2. 將該 <td> 的 height 屬性設為 0px。
3. 以 0.5px 為單位逐步增加 height 值，直到框線顯示正常為止。

範例程式碼如下：

string html = $@"
    <style>
        table.list, table.list td {{
            border-collapse: collapse;
            border: 1px solid black;
        }}
    </style>
    <table>
        <tr>
            <td>
                <table class=""list"">
                    <tr><td>內容</td></tr>
                    <!-- 透過額外的 tr 進行高度微調 -->
                    <tr>
                        <td style=""height: 9px;""></td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
";

---

異動歷程

1. 2023-12-05

   • 初版文件建立。