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 limites silábicos 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 carregamento de padrões local e remoto, comportamento de fallback, limitações, tratamento 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 ``
  3. Defina para um novo com um `` caminho ou URL
  4. Inclua `` no CSS do conteúdo HTML.
  5. Chame `` e salve o resultado.

Como Funciona a Hifenização Personalizada na Renderização de PDFs?

A classe 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 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 as regras de padrões 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 (iniciando 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 e seu em fornecem predefinições integradas para inglês (EUA), inglês (britânico) e russo. A propriedade tem precedência sobre esta enumeração quando ambas estão definidas, seguindo uma cadeia de prioridade clara:

  1. Hifenização personalizada — se definida com um `` válido, 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 `` também estiver configurado, o renderizador recorrerá a 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 `` para um URL remoto é a maneira mais rápida de aplicar hifenização personalizada sem incluir 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.

As declarações CSS e são necessárias para compatibilidade com o Chromium. A regra `` 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 contêiner de página HTML, o que resultará em falha na validação do padrão. 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
Ahmad Sohail
Ahmad Sohail
  Converse agora mesmo com a equipe de engenharia.
Desenvolvedor Full Stack

Ahmad é um desenvolvedor full-stack com uma sólida base em C#, Python e tecnologias web. Ele tem um grande interesse em construir soluções de software escaláveis e gosta de explorar como design e funcionalidade se encontram em aplicações do mundo real.

Antes de se ...

Leia mais
Pronto para começar?
Nuget Downloads 18,926,724 | Versão: 2026.5 just released
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