如何在C# PDF生成中添加自定义断字
在C# PDF生成中，自定义断字有助于修复狭窄列、发票、合同和多语言报告中的尴尬间距、词语溢出和劣质文本换行。 当PDF渲染器未应用正确的断字模式时，齐行文本可能会留下大间隙或在行间分布不均。
在IronPDF中，断字是在通过Chromium引擎的HTML到PDF渲染过程中处理的，而不是通过Word风格的文档对象模型。 CSS 的 hyphens: auto 属性允许渲染器在有效的音节分界处断开单词，而 IronPDF 在生成 PDF 时会应用此行为。 CustomHyphenation 属性在 ChromePdfRenderOptions 中控制使用哪种连字符模式。
模式文件使用TeX格式，可以从本地文件路径或远程URL加载。 这种方式使用户能够为不同语言和文档布局定义自定义断字规则，并在最终PDF中更好地控制单词断裂。
本指南详细说明了如何在 C# 中使用 CustomHyphenationDefinitions API，内容涵盖本地和远程模式加载、备用方案、限制条件、错误处理以及缓存机制。
使用 NuGet 安装
快速入门
-
使用 NuGet 包管理器安装 https://www.nuget.org/packages/IronPdf
PM > Install-Package IronPdf -
复制并运行这段代码。
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"); -
部署到您的生产环境中进行测试
通过免费试用立即在您的项目中开始使用IronPDF
最小化工作流程
- 安装IronPDF NuGet包
- 创建一个 `` 实例
- 将
设置为新的，并指定 `` 的路径或 URL - 在 HTML 内容的 CSS 中包含 ``
- 调用 `` 并保存结果
自定义断字在PDF渲染中如何工作？
类定义了 IronPDF 在渲染过程中从何处加载连字规则。 Chromium 引擎会读取这些模式，并在 HTML 元素上存在 CSS 规则时应用它们。
CustomHyphenationDefinitions类是什么？
类公开了两个属性：
| 属性 | 翻译类型 | 必需的 | 说明 |
|---|---|---|---|
PatternSource | 字符串 | 是 | 断字模式文件的路径或URL（例如，hyph-en-us.pat.txt） |
ExceptionSource | 字符串 | 无 | 断字例外文件的路径或URL（例如，hyph-en-us.hyp.txt） |
模式文件遵循tex-hyphen项目在GitHub上的页面维护的TeX断字格式。 每个语言版本在代码库中包含两个文件：hyph-{lang}.pat.txt 用于模式规则，hyph-{lang}.hyp.txt 用于例外列表。引用 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");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声明，自定义模式将被加载但不会被应用。
https://github.com/hyphenation/tex-hyphen/blob/master/... 的标准 GitHub URL 会返回一个 HTML 页面封装，这将导致模式验证失败。 请使用 https://raw.githubusercontent.com/... 格式，或点击 GitHub 上的"原始"按钮以获取正确的 URL。）}]远程资源约束是什么？
| 约束 | Value |
|---|---|
| 协议 | HTTP和HTTPS（推荐使用HTTPS） |
| 允许的内容类型 | text/plain, application/octet-stream |
| 最大响应大小 | 5 MB |
| 请求超时 | 10秒 |
| 安全 | 请求到私有/本地IP（10.x.x.x、192.168.x.x、localhost）被阻止，以防止SSRF攻击 |
| 拒绝的内容 | 二进制文件、包含空字节的文件、包含 |
免费开始
免费开始
预定免费现场演示
无需信用卡或创建账户
