1. IronPDF
  2. Tutoriais
  3. Hifenização Personalizada

Como Adicionar Hifenização Personalizada à Geração de PDF em C

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

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 fronteiras de sílabas válidas, 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 carregamento de padrões locais e remotos, comportamento de fallback, limitações, manuseio de erros e cache.

NuGet Instalar com NuGet

PM >  Install-Package IronPdf

Confira o IronPDF no NuGet para uma instalação rápida. Com mais de 10 milhões de downloads, ele está transformando o desenvolvimento de PDFs com C#. Você também pode baixar o arquivo DLL ou o instalador para Windows .

Início Rápido

  1. Instale IronPDF com o Gerenciador de Pacotes NuGet

    PM > Install-Package IronPdf

  2. Copie 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");

  3. Implante para testar em seu ambiente de produção.

    Comece a usar IronPDF em seu projeto hoje com uma avaliação gratuita

    arrow pointer

Fluxo de Trabalho Mínimo

  1. Instale o pacote NuGet do IronPDF
  2. Crie uma instância de ChromePdfRenderer
  3. Defina RenderingOptions.CustomHyphenation para um novo CustomHyphenationDefinitions com um caminho ou URL PatternSource
  4. Inclua hyphens: auto no CSS do conteúdo HTML
  5. Chame 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 motor Chromium lê esses padrões e os aplica quando a regra CSS hyphens: auto está presente em um elemento HTML.

O que é a Classe CustomHyphenationDefinitions?

A classe expõe duas propriedades:

Tabela 1: Propriedades de CustomHyphenationDefinitions
PropriedadeTipoObrigatórioDescrição
FontedePadrõesstringSimCaminho ou URL para o arquivo de padrões de hifenização (ex: hyph-en-us.pat.txt)
FonteExceçãostringNãoCaminho 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 possui 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 de conteúdo bruto (começando com https://raw.githubusercontent.com/) — uma URL padrão de página do GitHub retorna HTML, não o texto do padrão.

Como a Hifenização Personalizada Substitui a Configuração de Idioma Integrada?

O enum HyphenationLanguage em ChromePdfRenderOptions fornece predefinições embutidas para Inglês (EUA), Inglês (Britânico) e Russo. A propriedade CustomHyphenation tem precedência sobre este enum quando ambos são configurados, seguindo uma cadeia de prioridade clara:

  1. CustomHyphenation — se configurado com uma FontePadrão válida, padrões personalizados são usados
  2. HyphenationLanguage — se nenhum padrão personalizado estiver configurado, a predefinição de idioma integrada se aplica
  3. 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 de HyphenationLanguage também estiver configurado, o renderizador recai para 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 o FontedePadrões para uma URL remota é 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");
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")
$vbLabelText   $csharpLabel

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.

Ambos os hyphens: auto e -webkit-hyphens: auto declarações CSS são necessárias para compatibilidade com o Chromium. A regra text-align: justify 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.

ObserveA URL deve apontar para o conteúdo de texto bruto. Uma URL padrão do GitHub como https://github.com/hyphenation/tex-hyphen/blob/master/... retorna um envoltório de página HTML, o que falhará na validação de padrões. Use o formulário https://raw.githubusercontent.com/... ou clique no botão "Raw" no GitHub para obter a URL correta.

Quais São as Restrições de Fonte Remota?

Tabela 2: Restrições de URL Remoto
RestriçãoValor
ProtocolosHTTP e HTTPS (HTTPS recomendado)
Tipos de conteúdo permitidostext/plain, application/octet-stream
Tamanho máximo da resposta5 MB
Tempo limite da solicitação10 segundos
SegurançaRequisições para IPs privados/locais (10.x.x.x, 192.168.x.x, localhost) são bloqueadas para prevenir ataques SSRF
Conteúdo rejeitadoArquivos binários, arquivos com bytes nulos, arquivos contendo tags
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas? PM > Install-Package IronPdf
executar um exemplo Veja seu HTML se transformar em um PDF.

Teste grátis por 30 dias → Produto completo. Sem limites. Sem cartão. Comece seu teste gratuito

Equipe de suporte de ferro

Estamos online 24 horas por dia, 5 dias por semana.
Bater papo
E-mail
Liga para mim