1. IronPDF
  2. 操作指南
  3. 自訂連字符號

如何在 C# 中為 PDF 生成功能新增自訂分字功能

Ahmad Sohail
Ahmad Sohail
更新:
This article was translated from English: Does it need improvement?
Translated
View the article in English

C# PDF 生成中的自訂連字功能，有助於修正狹窄欄位、發票、合約及多語言報告中出現的尷尬間距、文字溢出及不良的文字換行問題。 當 PDF 渲染器未套用正確的連字模式時，兩端對齊的文字可能會留下大段空白，或出現不當的換行。

在 IronPDF 中，連字處理是在透過 Chromium 引擎進行 HTML 轉 PDF 渲染時處理的，而非透過 WORD 風格的文件物件模型。 CSS 的 hyphens: auto 屬性允許渲染器在有效的音節分界處進行斷字，而 IronPDF 會在生成 PDF 時套用此行為。 ChromePdfRenderOptions 中的 CustomHyphenation 屬性用於控制應採用何種連字模式。

範本檔案採用 TeX 格式，可從本地檔案路徑或遠端網址載入。 這使得能夠針對不同語言和文件版面定義自訂的連字規則，並對最終 PDF 中的斷字有更細緻的控制。

本指南說明如何在 C# 中使用 CustomHyphenationDefinitions API，內容涵蓋本地與遠端模式載入、備用行為、限制、錯誤處理及快取。

NuGet 透過 NuGet 安裝

PM >  Install-Package IronPdf

請至 NuGet 查閱 https://www.nuget.org/packages/IronPdf 以快速安裝。該套件下載量已突破 1,000 萬次，正透過 C# 徹底改變 PDF 開發領域。 您亦可下載 DLL 檔案或 Windows 安裝程式。

快速入門

  1. using NuGet 套件管理員安裝 https://www.nuget.org/packages/IronPdf

    PM > Install-Package IronPdf

  2. 請複製並執行此程式碼片段。

    using IronPdf;

// Create renderer and assign custom hyphenation patterns from a remote URL
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource = "https://raw.githubusercontent.com/hyphenation/tex-hyphen/master/hyph-utf8/tex/generic/hyph-utf8/patterns/txt/hyph-en-us.pat.txt",
    ExceptionSource = "https://raw.githubusercontent.com/hyphenation/tex-hyphen/master/hyph-utf8/tex/generic/hyph-utf8/patterns/txt/hyph-en-us.hyp.txt"
};

// Render HTML with CSS hyphens:auto to trigger word breaking
var pdf = renderer.RenderHtmlAsPdf("<div style='text-align:justify; hyphens:auto; width:120px;'>Supercalifragilisticexpialidocious</div>");
pdf.SaveAs("hyphenated.pdf");

  3. 部署至您的生產環境進行測試

    立即透過免費試用，在您的專案中開始使用 IronPDF

    arrow pointer

簡化工作流程

  1. 安裝 IronPDF NuGet 套件
  2. 建立一個 `` 實例
  3. 將 設定為新的，並使用 ``路徑或網址
  4. 請在 HTML 內容的 CSS 中加入 ``
  5. 呼叫 `` 並儲存結果

PDF 渲染中的自訂連字功能如何運作？

類別定義了 IronPDF 在渲染過程中從何處載入分字規則。 Chromium 引擎會讀取這些模式，並在 HTML 元素上出現 CSS 規則時套用這些模式。

什麼是 CustomHyphenationDefinitions 類別？

該類別公開了兩個屬性：

表 1：CustomHyphenationDefinitions 屬性
屬性類型必備描述
PatternSourcestring是分字模式檔案的路徑或 URL（例如， hyph-en-us.pat.txt)
ExceptionSourcestring否分字例外檔案的路徑或 URL（例如， hyph-en-us.hyp.txt)

範本檔案遵循由 GitHub 上 tex-hyphen 專案維護的 TeX 斷字格式。 每個語言版本在儲存庫中皆有兩個檔案：hyph-{lang}.pat.txt 用於模式規則，hyph-{lang}.hyp.txt 用於例外清單。引用 GitHub 上的檔案時，必須提供原始內容的 URL（以 https://raw.githubusercontent.com/ 開頭）——標準的 GitHub 頁面 URL 會返回 HTML 內容，而非模式文字。

自訂連字法會覆寫內建的語言設定嗎？

枚舉及其 選項，位於 中，提供英文（美國）、英文（英國）及俄文的內建預設值。 當 屬性與此枚舉皆被設定時，前者將優先於後者，遵循明確的優先順序鏈：

  1. 自訂連字 — 若設定有效的 ``，則使用自訂模式
  2. 連字規則 — 若未設定自訂模式，則套用內建的語言預設值
  3. 無 — 若兩者皆未設定，則不進行分字處理

自訂模式載入失敗時會發生什麼情況？

載入範本時若發生錯誤，系統會記錄該錯誤但不會拋出例外。渲染操作將繼續進行（不進行分字處理），而非導致失敗。 若同時設定了 `` 值，渲染器將回退至該內建預設值。

這種"靜默失敗"的行為是針對生產環境所做的刻意設計選擇。 無論是因取得遠端範本檔案時發生網路超時、檔案路徑無效、DNS 解析失敗，或是範本內容格式錯誤，都不會導致渲染流程當機。PDF 仍會生成——只是缺少了連字號分隔的換行。

其取捨在於能見度。 若在首次載入時遇到錯誤的範本檔案或無法存取的 URL，將會在後續使用相同來源值的每次渲染時，默默地產生影響（因為快取也會儲存失敗狀態）。 建議在應用程式啟動時或 CI/CD 部署檢查階段驗證模式檔案並確認對遠端 URL 的網路存取權限，而非在渲染時進行。