カスタムハイフネーションをPDF生成に追加する方法 in C#
C#のPDF生成におけるカスタムハイフネーションは、狭い列、請求書、契約書、多言語レポートでの不必要なスペース、文字のオーバーフロー、そして貧弱なテキストの折返しを修正するのに役立ちます。 PDFレンダラが適切なハイフネーションパターンを適用しない場合、均等割付されたテキストは大きなギャップを残したり、行を渡って無理に分割されたりする可能性があります。
IronPDFでは、HTMLからPDFへのレンダリング中にChromiumエンジンを介してハイフネーションが処理され、Wordスタイルの文書オブジェクトモデルでは処理されません。 CSSのhyphens: autoプロパティを使用すると、レンダラーは有効な音節の区切りで単語を分割できるようになり、IronPDFはPDF生成時にこの動作を適用します。 CustomHyphenation プロパティは、ChromePdfRenderOptions 内でどのハイフネーションパターンを使用するかを制御します。
パターンファイルはTeX形式を使用し、ローカルファイルパスまたはリモートURLからロード可能です。 これにより、最終的なPDFでの単語の区切りについて、さまざまな言語と文書レイアウトにカスタムのハイフネーションルールを定義することが可能となり、より多くの制御が可能になります。
このガイドでは、C# での CustomHyphenationDefinitions API の使用方法について、ローカルおよびリモートのパターン読み込み、フォールバック動作、制限事項、エラー処理、キャッシュなどを含めて説明します。
NuGetでインストール-
1Install IronPDF with NuGet Package Manager
-
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");C# -
3実際の環境でテストするためにデプロイする
今日プロジェクトで IronPDF を使い始めましょう無料トライアル
最小限のワークフロー
- IronPDF NuGetパッケージをインストールする
- ``のインスタンスを作成する
を新しいとして、`` パスまたは URL を指定してください- HTMLコンテンツのCSSに `` を含める
- `` を呼び出し、結果を保存します
PDFレンダリングでカスタムハイフネーションはどのように機能するのか？
クラスは、レンダリング処理中に IronPDF がハイフネーション規則をどこから読み込むかを定義します。 Chromiumエンジンはこれらのパターンを読み取り、HTML要素にCSSのルールが存在する場合にそれらを適用します。
CustomHyphenationDefinitionsクラスとは何か？
このクラスは2つのプロパティを公開します:
| プロパティ | タイプ | 必須 | 翻訳内容 |
|---|---|---|---|
PatternSource | 文字列 | はい | ハイフネーションパターンファイルのパスまたはURL (例: hyph-en-us.pat.txt) |
ExceptionSource | 文字列 | なし | ハイフネーション例外ファイルのパスまたはURL (例: hyph-en-us.hyp.txt) |
パターンファイルは、GitHubのtex-hyphenプロジェクトによって維持されるTeXハイフネーションフォーマットに従います。 各言語のリポジトリには、パターンルールを記述した hyph-{lang}.pat.txt と例外リストを記述した hyph-{lang}.hyp.txt の2つのファイルがあります。GitHub上にホストされているファイルを参照する際は、生のコンテンツURL（https://raw.githubusercontent.com/ で始まるもの）が必要です。標準的なGitHubページのURLでは、パターンテキストではなくHTMLが返されるためです。
カスタムハイフネーションが組み込みの言語設定を上書きする際の動作は？
列挙型とその には、における英語（米国）、英語（英国）、およびロシア語用の組み込みプリセットが用意されています。 プロパティは、両方が設定されている場合、明確な優先順位に従って、この列挙型よりも優先されます：
- カスタムハイフネーション — 有効な `` が設定されている場合、カスタムパターンが使用されます
- HyphenationLanguage — カスタムパターンが設定されていない場合、組み込み言語プリセットが適用されます
- なしne — 両方が設定されていない場合、ハイフネーションは行われません
カスタムパターンの読み込みが失敗した場合はどうなるか？
**パターン読み込み中のエラーはログに記録されますが、例外をスローしません。**レンダー操作は失敗することなく、ハイフネーションなしで続行します。 `` の値も設定されている場合、レンダラーはその組み込みプリセットにフォールバックします。
このサイレントフェイルの動作は、製品環境のための意図的な設計選択です。 リモートパターンファイルの取得中のネットワークタイムアウト、無効なファイルパス、DNS解決失敗、または不正なパターンコンテンツは、レンダリングパイプラインをクラッシュさせません。PDFはまだ生成されます - ただし、ハイフネーションされた単語区切りは欠如します。
トレードオフは可視性です。 最初のロード時に不良のパターンファイルまたは到達不能なURLは、それらが同じソース値を使用するすべての後続のレンダーに静かに影響を与えます（キャッシュも失敗状態を保存するためです）。 推奨事項は、パターンファイルを検証し、アプリケーションのスタートアップやCI/CDのデプロイチェック時にリモートURLへのネットワークアクセスを確認することです - レンダー時ではなく。
パターンファイルをリモートURLからロードする方法
`` をリモート URL に指定することは、ファイルをプロジェクトにバンドルすることなく、カスタムハイフネーションを適用する最も迅速な方法です。 以下の例は、米国 のパターンをtex-hyphenリポジトリからロードし、整列したテキストブロックをレンダリングします。
using IronPdf;
var renderer = new ChromePdfRenderer();
// Load custom patterns from a remote TeX hyphenation repository
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"
};
string html = @"
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
.narrow-column {
width: 150px;
text-align: justify;
hyphens: auto;
-webkit-hyphens: auto;
border: 1px solid #ccc;
padding: 10px;
}
</style>
</head>
<body>
<div class='narrow-column'>
The extraordinarily sophisticated implementation demonstrates
how hyphenation significantly improves the typographical quality
of justified text in constrained column widths.
</div>
</body>
</html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("remote-hyphenation.pdf");Imports IronPdf
Dim renderer As New ChromePdfRenderer()
' Load custom patterns from a remote TeX hyphenation repository
renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
.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"
}
Dim html As String = "
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
.narrow-column {
width: 150px;
text-align: justify;
hyphens: auto;
-webkit-hyphens: auto;
border: 1px solid #ccc;
padding: 10px;
}
</style>
</head>
<body>
<div class='narrow-column'>
The extraordinarily sophisticated implementation demonstrates
how hyphenation significantly improves the typographical quality
of justified text in constrained column widths.
</div>
</body>
</html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("remote-hyphenation.pdf")出力
レンダリングされたPDFは、音節境界で単語がきれいに切れる整えられた段落を示しています。 ハイフネーションがない場合、この同じテキストは単語間の大きなギャップを生むか、列から溢れるでしょう。
Chromiumとの互換性を確保するため、のCSS宣言が必要です。 ルールにより、ハイフネーションが最も目立つようになります。 ターゲットHTML要素にどちらのCSS宣言も存在しない場合、カスタムパターンは読み込まれますが適用されません。
[[i:(URLは生のテキストコンテンツを指している必要があります。 https://github.com/hyphenation/tex-hyphen/blob/master/... のような標準的な GitHub URL は HTML ページラッパーを返すため、パターン検証に失敗します。 https://raw.githubusercontent.com/... 形式を使用するか、GitHub の"Raw"ボタンをクリックして正しい URL を取得してください。）]])}]
リモートソース制約とは何ですか？
| 制約 | 値 |
|---|---|
| プロトコル | HTTPおよびHTTPS（HTTPS推奨） |
| 許可されるコンテンツタイプ | text/plain, application/octet-stream |
| 最大応答サイズ | 5 MB |
| リクエストタイムアウト | 10秒 |
| セキュリティ | プライベート/ローカルIPへのリクエスト (10.x.x.x, 192.168.x.x, localhost) はSSRF攻撃を防ぐためにブロックされます |
| 拒否されたコンテンツ | バイナリファイル、ヌルバイトを含むファイル、<script>タグを含むファイル |
コンテナおよびクラウド環境 (Docker, Azure, AWS) は、リモートロードが成功するために、パターンファイルホストへの外向きHTTPSアクセスが必要です。
私のお気に入りのこの種のライブラリはIronPDFです。PDFファイルの迅速で効率的な操作が可能です。また、PDF/A形式へのエクスポートやPDF文書へのデジタル署名といった多くの貴重な機能も備えています。
ローカルファイルからパターンファイルをどうやって読み込むのですか？
外部ネットワークへのアクセスが制限されている環境や、ビルド時のバンドルを好む環境では、``はローカルファイルシステムのパスも受け付けます：
[[i:(パターンファイルは実行前にディスクに存在している必要があります。 tex-hyphenリポジトリからhyph-en-us.hyp.txtをダウンロードし、コードで参照されているパスに配置してください。）]])}]
using IronPdf;
var renderer = new ChromePdfRenderer();
// Load English hyphenation patterns from local files
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
PatternSource = @"C:\patterns\hyph-en-us.pat.txt",
ExceptionSource = @"C:\patterns\hyph-en-us.hyp.txt"
};
string html = @"
<html>
<head>
<style>
.invoice-container {
width: 220px;
text-align: justify;
hyphens: auto;
-webkit-hyphens: auto;
font-family: Georgia, serif;
font-size: 11px;
line-height: 1.5;
border: 1px solid #ddd;
padding: 12px;
}
h3 { font-size: 13px; margin-top: 0; }
.terms { color: #555; margin-top: 10px; font-size: 9px; }
</style>
</head>
<body>
<div class='invoice-container'>
<h3>Invoice #20260331</h3>
<p>なしndiscrimination acknowledgement: The undersigned
representative hereby confirms that all pharmaceutical
reimbursement documentation has been independently
verified and cross-referenced against the applicable
regulatory framework established by the appropriate
governmental oversight authority.</p>
<p class='terms'>なしtwithstanding any indemnification
provisions, the counterparty's disproportionate
liability shall not exceed the predetermined
recharacterization threshold established under the
intergovernmental cooperation agreement.</p>
</div>
</body>
</html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("local-hyphenation.pdf");出力
以下のように、さもないと溢れたりスペーシングが過剰になる長い単語が、自動的に音節境界で分割されています。 エンジンは必要な場合にのみハイフネーションを適用します。— 行にきれいに収まる単語は分割されません。
別の言語に切り替える場合は、ファイルパスを変更するだけです：
// Switch to French hyphenation — just change the file paths
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
PatternSource = @"C:\patterns\hyph-fr.pat.txt",
ExceptionSource = @"C:\patterns\hyph-fr.hyp.txt"
};' Switch to French hyphenation — just change the file paths
renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
.PatternSource = "C:\patterns\hyph-fr.pat.txt",
.ExceptionSource = "C:\patterns\hyph-fr.hyp.txt"
}このため、``列挙型では対応していない言語において、特に有用です。現在、この列挙型は英語（米国）、英語（英国）、およびロシア語のみをサポートしています。
ローカルファイル制約とは何ですか？
| 制約 | 値 |
|---|---|
| 許可される拡張子 | .txt, .pat |
| 最大ファイルサイズ | 5 MB |
| エンコーディング | UTF-8 |
| コンテンツルール | 有効なハイフネーションパターンのみ — コメント、メタデータ、ヘッダー、TeXディレクティブ、またはエンコーディングノートは不要 |
| 拒否されたコンテンツ | バイナリファイル、ヌルバイトを含むファイル、<script>タグを含むファイル |
バッチレンダリングにおけるキャッシングはパフォーマンスにどのように影響しますか？
カスタムハイフネーションパターンは、初回読み込み後にメモリにキャッシュされ、および の値をキーとして保存されます。 同じソースパスまたはURLを参照する後続のレンダリングは、キャッシュされたパターンを再ダウンロードまたは再読み込みせずに再利用します。
この動作には、大容量のPDFレンダリングワークフローにおける2つの実用的な意味があります：
パフォーマンス: 最初のレンダリングはI/Oコスト（ネットワークリクエストまたはディスク読み込み）を伴います。 その後のレンダリングは、パターン読み込みの観点から実質的に無料です。同じハイフネーション構成で数百のPDFを生成するバッチジョブの場合、オーバーヘッドはごくわずかです。
サイレントフェイルの持続: パターン読み込み中のエラーは例外を投げず、レンダラはハイフネーションなしで続行するため、最初のロードでの悪いパターンファイルやネットワークの失敗はバッチ全体を通じてサイレントに持続します。 その後のすべてのレンダリングもハイフネーションが不足し、追加のエラー信号はありません。 アプリケーションの起動時またはデプロイメント時にパターンファイルを検証し、URLのアクセス可能性を確認してください——レンダリング時ではなく。
キャッシュキーの識別子: キャッシュキーは、（および設定されている場合は ）の正確な文字列値です。 同じURLまたはファイルパスを指す2つのレンダラインスタンスは、同じキャッシュされたパターンを共有します。 URLを変更すると、同じファイルの異なるバージョンであっても、新たにロードされます。
本番デプロイメント前にファイル内容を事前に検証してください。 パターンファイルには有効なハイフネーションテキストのみを含める必要があります。 コメント、TeXディレクティブ、エンコーディング宣言、または非パターンコンテンツが存在すると、統合が失敗します。 tex-hyphenリポジトリは、数十の言語のための事前構築されたクリーンなパターンファイルを提供します。
リモートパターンソースにはHTTPSを推奨します。 HTTPはサポートされていますが、ファイルコンテンツのトランスポートレイヤー保護を提供しません。
次のステップは何ですか?
プロパティの 属性は、-CODE-965--@@ プロパティは、TeX パターンファイルでサポートされているあらゆる言語の語句分割動作を直接制御します。これは、 を通じて利用可能な 3 つの組み込みプリセットの範囲を超えた機能を提供します。 パターンファイルはリモートURLまたはローカルパスから読み込まれ、初回使用後にメモリにキャッシュされます。読み込みに失敗した場合は、設定にフォールバックします。 エラーはログに記録されますが、スローされることはないため、パターン検証はレンダリング時ではなくデプロイメント時に行うべきです。
関連するIronPDFレンダリング構成については、以下を参照してください:
ChromePdfRenderOptions利用可能なすべてのレンダリングオプションに関するAPIリファレンスPdfHyphenationLanguage組み込み言語プリセット用の列挙型- 完全なHTMLレンダリングパイプラインについては、HTMLからPDFへのレンダリングチュートリアルをご覧ください
- ChromePdfRenderOptions構成の他の手法については、レンダリングオプションのハウツーをご覧ください
- PDF生成と操作の全機能セットについては、IronPDF機能の概要をご覧ください
無料の30日間トライアルのIronPDFを入手して、ライブプロジェクトでカスタムハイフネーションを試し、または製品導入用のライセンスオプションを表示してください。
CustomHyphenationDefinitionsstring@@--CODE-974--@@@@--CODE-975--@@@@--CODE-976--@@@@--CODE-977--@@@@--CODE-978--@@@@--CODE-979--@@hyph-en-us.pat.txt@@--CODE-980--@@@@--CODE-981--@@@@--CODE-982--@@@@--CODE-983--@@
よくある質問
C#を使用してPDF生成でカスタムハイフネーションを実装するにはどうすればよいですか？
IronPDFを使用してPDF生成でカスタムハイフネーションを実装できます。URLまたはローカルファイルからTeXハイフネーションパターンをロードすることで、C#でPDFを生成する際に語の切り分けを制御できます。
TeXハイフネーションパターンとは何であり、それらはIronPDFでどのように使用されますか？
TeXハイフネーションパターンは、適切なハイフネーションポイントで語を切り分けるルールのセットです。IronPDFは、これらのパターンをロードして、生成されたPDFでの語のハイフネーションを管理することができます。
IronPDFでURLからハイフネーションパターンをロードできますか？
はい、IronPDFはURLから直接ハイフネーションパターンをロードすることをサポートしており、C# PDFプロジェクトでの動的で柔軟な語の切り分け構成を可能にします。
IronPDFでハイフネーションパターンにローカルファイルを使用することは可能ですか？
もちろん、IronPDFはローカルファイルからのカスタムハイフネーションパターンのロードを許可しており、PDF内の語のハイフネーションに対する正確な制御を提供します。
IronPDFでカスタムハイフネーションを使用する際の制約は何ですか？
IronPDFでカスタムハイフネーションを使用する際は、パターンが正しくフォーマットされており、意図した言語とドキュメントレイアウトの要件に適合していることを保証する必要があります。
私のPDFドキュメントでなぜカスタムハイフネーションが必要ですか？
カスタムハイフネーションは、特に複雑な言語固有の語の切り分けに対処する場合に、PDFドキュメントの可読性を向上させ、一貫したフォーマットを保証するために役立ちます。
IronPDFは、カスタムハイフネーションを実装するためのコード例を提供していますか？
はい、IronPDFは、C#プロジェクトでカスタムハイフネーションを実装しやすくするためのコード例を提供しており、PDF生成プロセスへのこの機能の統合を容易にします。
カスタムハイフネーションは、どのようにしてPDF生成を改善しますか？
カスタムハイフネーションは、語の切り分けに対する正確な制御を可能にし、異なる言語や形式にわたってドキュメントの外観と可読性を向上させることで、PDF生成を改善します。
Curtis Chauは、カールトン大学でコンピュータサイエンスの学士号を取得し、Node.js、TypeScript、JavaScript、およびReactに精通したフロントエンド開発を専門としています。直感的で美しいユーザーインターフェースを作成することに情熱を持ち、Curtisは現代のフレームワークを用いた開発や、構造の良い視覚的に魅力的なマニュアルの作成を楽しんでいます。
