Como Adicionar Hifenização Personalizada à Geração de PDF em C#
A hifenização personalizada em geração de PDF C# ajuda a corrigir espaçamento inadequado, estouro de palavras e quebra pobre de texto em colunas estreitas, faturas, contratos e relatórios multilíngues. Quando um renderizador de PDF não aplica os padrões corretos de hifenização, o texto justificado pode deixar grandes espaços ou se quebrar de forma inadequada nas linhas.
Não IronPDF, a hifenização é tratada durante a renderização de HTML para PDF através do motor Chromium, não através de um modelo de objeto de documento ao estilo Word. A propriedade CSS hyphens: auto permite que o renderizador quebre palavras em limites de sílabas válidos, e o IronPDF aplica esse comportamento durante a geração do PDF. A propriedade CustomHyphenation em ChromePdfRenderOptions controla quais padrões de hifenização são usados.
Os arquivos de padrão usam o formato TeX e podem ser carregados tanto de um caminho de arquivo local quanto de uma URL remota. Isso torna possível definir regras de hifenização personalizadas para diferentes idiomas e layouts de documentos, com mais controle sobre quebras de palavras no PDF final.
Este guia explica como usar a API CustomHyphenationDefinitions em C#, incluindo o carregamento de padrões locais e remotos, comportamento de fallback, limitações, tratamento de erros e cache.
Instalar com NuGet-
1Install IronPDF with NuGet Package Manager
-
2Copie e execute este trecho de código.
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# -
3Implante para testar em seu ambiente de produção.
Comece a usar IronPDF em seu projeto hoje com uma avaliação gratuita
Fluxo de Trabalho Mínimo
- Instale o pacote NuGet do IronPDF
- Crie uma instância
renderer - Defina
renderer.CustomHyphenationcomo um novoCustomHyphenationDefinitionscom um caminho ou URLPatternSource - Inclua
hyphensno CSS do conteúdo HTML - Chame
renderer.RenderHtmlAsPdf()e salve o resultado
Como Funciona a Hifenização Personalizada na Renderização de PDFs?
A classe CustomHyphenationDefinitions define de onde o IronPDF carrega as regras de hifenização durante o processo de renderização. O mecanismo Chromium lê esses padrões e os aplica quando a regra CSS hyphens está presente em um elemento HTML.
O que é a Classe CustomHyphenationDefinitions?
A classe expõe duas propriedades:
| Propriedade | Tipo | Obrigatório | Descrição |
|---|---|---|---|
PatternSource | string | Sim | Caminho ou URL para o arquivo de padrões de hifenização (ex: hyph-en-us.pat.txt) |
ExceptionSource | string | Não | Caminho ou URL para o arquivo de exceções de hifenização (ex: hyph-en-us.hyp.txt) |
Os arquivos de padrão seguem o formato de hifenização TeX mantido pelo projeto tex-hyphen no GitHub. Cada idioma tem dois arquivos no repositório: hyph-{lang}.pat.txt para regras de padrão e hyph-{lang}.hyp.txt para a lista de exceções. Ao referenciar arquivos hospedados no GitHub, é necessário o URL do conteúdo bruto (começando com https://raw.githubusercontent.com/) — um URL de página padrão do GitHub retorna HTML, não o texto do padrão.
O que a Hifenização Personalizada Sobrescreve a Configuração de Idioma Integrada?
O enum PdfHyphenationLanguage e seus HyphenationLanguage em ChromePdfRenderOptions fornecem predefinições integradas para inglês (EUA), inglês (britânico) e russo. A propriedade CustomHyphenation tem precedência sobre este enum quando ambos são definidos, seguindo uma cadeia de prioridades clara:
- HifenizaçãoPersonalizada — se configurada com um
PatternSourceválido, padrões personalizados são usados - HyphenationLanguage — se nenhum padrão personalizado estiver configurado, a predefinição de idioma integrada se aplica
- Nenhum — se nenhum estiver configurado, não ocorre hifenização
O que Acontece Quando o Carregamento de Padrões Personalizados Falha?
Erros durante o carregamento de padrões são registrados, mas não lançam exceções. A operação de renderização continua sem hifenização em vez de falhar. Se um valor HyphenationLanguage também está configurado, o renderizador recai sobre essa predefinição integrada.
Esse comportamento de falha silenciosa é uma escolha de design deliberada para ambientes de produção. Um tempo limite de rede ao buscar um arquivo de padrão remoto, um caminho de arquivo inválido, uma falha de resolução DNS ou conteúdo de padrão malformado não interromperão o pipeline de renderização. O PDF ainda será gerado - ele apenas não terá quebras de palavra hifenizadas.
O compromisso é a visibilidade. Um arquivo de padrão incorreto ou URL inacessível no primeiro carregamento afetará silenciosamente todas as renderizações subsequentes usando esses mesmos valores de origem (pois o cache também armazena o estado de falha). A recomendação é validar os arquivos de padrão e confirmar o acesso à rede para URLs remotas durante a inicialização do aplicativo ou verificações de implantação CI/CD - não no momento da renderização.
Como os Arquivos de Padrão Podem Ser Carregados de uma URL Remota?
Apontar PatternSource para um URL remoto é a maneira mais rápida de aplicar hifenização personalizada sem embutir arquivos no projeto. O exemplo a seguir carrega padrões de inglês dos EUA. Padrões de inglês do repositório tex-hyphen e renderiza um bloco de texto justificado:
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")Saída
O PDF renderizado mostra o parágrafo justificado com quebras de palavras limpas nas fronteiras de sílabas. Sem hifenização, esse mesmo texto produziria grandes lacunas entre palavras ou transbordaria a coluna.
Ambas as declarações CSS hyphens e hyphenate-limit-chars são necessárias para compatibilidade com o Chromium. A regra hyphens torna a hifenização mais visível. Se nenhuma declaração CSS estiver presente nos elementos HTML alvo, os padrões personalizados são carregados mas nunca aplicados.
https://github.com/hyphenation/tex-hyphen/blob/master/... retorna um wrapper de página HTML, o que falhará na validação de padrão. Use https://raw.githubusercontent.com/... formulário, ou clique no botão "Raw" no GitHub para obter o URL correto.Quais São as Restrições de Fonte Remota?
| Restrição | Valor |
|---|---|
| Protocolos | HTTP e HTTPS (HTTPS recomendado) |
| Tipos de conteúdo permitidos | text/plain , application/octet-stream |
| Tamanho máximo da resposta | 5 MB |
| Tempo limite da solicitação | 10 segundos |
| Segurança | Requisições para IPs privados/locais (10.x.x.x, 192.168.x.x, localhost) são bloqueadas para prevenir ataques SSRF |
| Conteúdo rejeitado | Arquivos binários, arquivos com bytes nulos, arquivos contendo tags <script> |
Contêineres e ambientes em nuvem (Docker, Azure, AWS) devem ter acesso HTTPS de saída ao host do arquivo de padrões para que o carregamento remoto seja bem-sucedido.
Minha biblioteca favorita desse tipo é o IronPDF. Ele permite a manipulação rápida e eficiente de arquivos PDF. Além disso, possui muitos recursos valiosos, como a exportação para o formato PDF/A e a assinatura digital de documentos PDF.
Com o IronOCR, podemos economizar US$ 40.000 por ano em processamento manual, ao mesmo tempo que aumentamos a produtividade e liberamos recursos para tarefas de alto impacto. Eu o recomendo fortemente.
O IronSuite desempenha um papel crucial nas nossas operações. Estas são ferramentas que aumentam a eficiência no negócio, incluindo a criação de plantas baixas e melhoria na gestão de inventário.
Como os Arquivos de Padrão Podem Ser Carregados de Arquivos Locais?
Para ambientes onde o acesso a redes externas é restrito ou onde a empacotamento em tempo de compilação é preferido, PatternSource também aceita um caminho do sistema de arquivos local:
hyph-en-us.pat.txt e hyph-en-us.hyp.txt do repositório tex-hyphen e coloque-os no caminho referenciado pelo seu código.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>Nondiscrimination 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'>Notwithstanding 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");Imports IronPdf
Dim renderer As New ChromePdfRenderer()
' Load English hyphenation patterns from local files
renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
.PatternSource = "C:\patterns\hyph-en-us.pat.txt",
.ExceptionSource = "C:\patterns\hyph-en-us.hyp.txt"
}
Dim html As String = "
<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>Nondiscrimination 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'>Notwithstanding 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>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("local-hyphenation.pdf")Saída
Como pode ser visto abaixo, palavras longas que, de outra forma, transbordariam ou criariam espaçamento excessivo são quebradas automaticamente nas fronteiras de sílabas. O motor só hifeniza onde necessário — palavras que se encaixam sem problemas em uma linha são deixadas inteiras.
Mudar para outro idioma requer apenas uma alteração nos caminhos dos arquivos:
// 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"
}Isso torna CustomHyphenation particularmente útil para idiomas não cobertos pelo enum PdfHyphenationLanguage embutido, que atualmente suporta apenas inglês (EUA), inglês (britânico) e russo.
Quais São as Restrições de Arquivos Locais?
| Restrição | Valor |
|---|---|
| Extensões permitidas | .txt , .pat |
| Tamanho máximo do arquivo | 5 MB |
| Codificação | UTF-8 |
| Regras de conteúdo | Apenas padrões de hifenização válidos — sem comentários, metadados, cabeçalhos, diretivas TeX, ou notas de codificação |
| Conteúdo rejeitado | Arquivos binários, arquivos com bytes nulos, arquivos contendo tags <script> |
Como o Cache Afeta o Desempenho na Renderização em Lote?
Padrões de hifenização personalizados são armazenados em cache na memória após o primeiro carregamento, indexados pelos valores PatternSource e ExceptionSource. Renderizações subsequentes que referenciam os mesmos caminhos de origem ou URLs reutilizam os padrões em cache sem rebaixar ou reler os arquivos.
Esse comportamento tem duas implicações práticas para fluxos de trabalho de renderização de PDF em grande volume:
Desempenho: A primeira renderização incorre no custo de I/O (solicitação de rede ou leitura de disco). Cada renderização após isso é efetivamente gratuita do ponto de vista do carregamento de padrões. Para trabalhos em lote que geram centenas de PDFs com a mesma configuração de hifenização, a sobrecarga é insignificante.
Persistência de falha silenciosa: Porque erros durante o carregamento do padrão não lançam exceções e o renderizador continua sem hifenização, um arquivo de padrão ruim ou falha de rede no primeiro carregamento persistirá silenciosamente por todo o lote. Cada renderização subsequente também não terá hifenização, sem sinal de erro adicional. Validar os arquivos de padrão e confirmar a acessibilidade da URL durante a inicialização do aplicativo ou a implantação — não no momento da renderização.
Identidade da chave do cache: A chave do cache é o valor exato da string de PatternSource (e ExceptionSource se configurado). Duas instâncias de renderizador apontando para a mesma URL ou caminho de arquivo compartilham os mesmos padrões em cache. Alterar a URL — mesmo para uma versão diferente do mesmo arquivo — força um novo carregamento.
Pré-validar o conteúdo do arquivo antes da implantação na produção. Arquivos de padrões devem conter apenas texto de hifenização válido. A presença de comentários, diretivas TeX, declarações de codificação, ou qualquer conteúdo não-padrão provoca falha na integração. O repositório tex-hyphen fornece arquivos de padrões limpos predefinidos para dezenas de idiomas.
HTTPS é recomendado para fontes de padrões remotas. HTTP é suportado, mas não oferece proteção de camada de transporte para o conteúdo do arquivo.
Quais são os próximos passos?
A propriedade CustomHyphenation em ChromePdfRenderOptions oferece controle direto sobre o comportamento de quebra de palavras para qualquer idioma suportado por um arquivo de padrão TeX — estendendo-se além das três predefinições integradas disponíveis através de PdfHyphenationLanguage. Arquivos de padrão são carregados a partir de URLs remotos ou caminhos locais, são armazenados em cache na memória após o primeiro uso, e recuam para a configuração de HyphenationLanguage se o carregamento falhar. Erros são registrados, mas nunca lançados, portanto a validação do padrão deve ocorrer durante a implantação ao invés do tempo de renderização.
Para configuração de renderização relacionada ao IronPDF, consulte:
- Referência da API
ChromePdfRenderOptionspara todas as opções de renderização disponíveis - Enum
PdfHyphenationLanguagepara as predefinições de idioma embutidas - tutorial de renderização de HTML para PDF para toda a linha de renderização HTML
- como fazer opções de renderização para outra configuração de ChromePdfRenderOptions
- visão geral dos recursos do IronPDF para o conjunto completo de capacidades de geração e manipulação de PDF
Obtenha um teste gratuito de 30 dias do IronPDF para testar a hifenização personalizada em um projeto ao vivo, ou veja opções de licenciamento para implantação em produção.
ChromePdfRenderer PatternSource CustomHyphenationDefinitions string hyphens: auto RenderHtmlAsPdf CustomHyphenationDefinitions hyphens: auto HyphenationLanguage ChromePdfRenderOptions hyph-en-us.pat.txt -webkit-hyphens: auto text-align: justify PdfHyphenationLanguage ChromePdfRenderOptions
Perguntas frequentes
Como posso implementar hifenização personalizada na geração de PDF usando C#?
Você pode implementar hifenização personalizada na geração de PDF usando o IronPDF carregando padrões de hifenização TeX de URLs ou arquivos locais. Isso permite controlar a quebra de palavras ao gerar PDFs em C#.
O que são padrões de hifenização TeX e como eles são usados no IronPDF?
Os padrões de hifenização TeX são conjuntos de regras para quebrar palavras em pontos de hifenização adequados. O IronPDF permite carregar esses padrões para gerenciar como as palavras são hifenizadas nos seus PDFs gerados.
Posso carregar padrões de hifenização de uma URL no IronPDF?
Sim, o IronPDF suporta o carregamento de padrões de hifenização diretamente de URLs, permitindo configurações de quebra de palavras dinâmicas e flexíveis para seus projetos PDF em C#.
É possível usar arquivos locais para padrões de hifenização com o IronPDF?
Absolutamente, o IronPDF permite carregar padrões de hifenização personalizados de arquivos locais, oferecendo controle preciso sobre a hifenização de palavras em seus PDFs.
Quais são as restrições ao usar hifenização personalizada no IronPDF?
Ao usar hifenização personalizada no IronPDF, é necessário garantir que os padrões estejam formatados corretamente e que estejam alinhados com o idioma e requisitos de layout de documento pretendidos.
Por que eu precisaria de hifenização personalizada em meus documentos PDF?
A hifenização personalizada é útil para melhorar a legibilidade e garantir formatação consistente em documentos PDF, especialmente ao lidar com quebras de palavras específicas de idiomas complexos.
O IronPDF fornece exemplos de código para implementar hifenização personalizada?
Sim, o IronPDF fornece exemplos de código para ajudar a implementar hifenização personalizada em seus projetos C#, facilitando a integração desse recurso no processo de geração de PDF.
Como a hifenização personalizada melhora a geração de PDF?
A hifenização personalizada melhora a geração de PDF permitindo um controle preciso sobre quebras de palavras, o que aprimora a aparência e a legibilidade do documento em diferentes idiomas e formatos.
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.
