1. IronPDF
  2. Guías
  3. Guionización personalizada

Cómo agregar guionización personalizada a la generación de PDF en C

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

La guionización personalizada en la generación de PDF en C# ayuda a corregir espacios incómodos, desbordamiento de palabras y mala división de texto en columnas estrechas, facturas, contratos e informes multilingües. Cuando un renderizador de PDF no aplica los patrones de guionización correctos, el texto justificado puede dejar grandes espacios o dividirse mal en líneas.

En IronPDF, la guionización se maneja durante la renderización de HTML a PDF a través del motor Chromium, no mediante un modelo de objeto de documento al estilo de Word. La propiedad CSS hyphens: auto permite al renderizador dividir palabras en límites de sílabas válidos, e IronPDF aplica ese comportamiento durante la generación de PDF. La propiedad CustomHyphenation en ChromePdfRenderOptions controla qué patrones de guionización se utilizan.

Los archivos de patrones usan el formato TeX y pueden cargarse desde una ruta de archivo local o una URL remota. Esto permite definir reglas de guionización personalizadas para diferentes idiomas y diseños de documentos con mayor control sobre la división de palabras en el PDF final.

Esta guía explica cómo usar la API CustomHyphenationDefinitions en C#, incluida la carga de patrones locales y remotos, comportamiento de respaldo, limitaciones, manejo de errores y almacenamiento en caché.

NuGet Instalar con NuGet

PM >  Install-Package IronPdf

Echa un vistazo a IronPDF en NuGet para una instalación rápida. Con más de 10 millones de descargas, está transformando el desarrollo de PDF con C#. También puede descargar el DLL o el instalador de Windows.

Inicio rápido

  1. Instala IronPDF con el Administrador de Paquetes NuGet

    PM > Install-Package IronPdf

  2. Copie y ejecute este fragmento 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. Despliegue para probar en su entorno real

    Comienza a usar IronPDF en tu proyecto hoy mismo con una prueba gratuita

    arrow pointer

Flujo de trabajo mínimo

  1. Instala el paquete IronPDF de NuGet
  2. Crea una instancia de ChromePdfRenderer
  3. Establece RenderingOptions.CustomHyphenation en un nuevo CustomHyphenationDefinitions con una ruta de PatternSource o URL
  4. Incluye hyphens: auto en el CSS del contenido HTML
  5. Llama a RenderHtmlAsPdf y guarda el resultado

¿Cómo funciona la guionización personalizada en la renderización de PDF?

La clase CustomHyphenationDefinitions define de dónde IronPDF carga las reglas de guionización durante el proceso de renderización. El motor de Chromium lee estos patrones y los aplica cuando la regla hyphens: auto de CSS está presente en un elemento HTML.

¿Qué es la clase CustomHyphenationDefinitions?

La clase expone dos propiedades:

Tabla 1: Propiedades de CustomHyphenationDefinitions
PropiedadEscriba aRequeridoDescripción
PatternSourcecadenaSíRuta o URL al archivo de patrones de guionización (p. ej., hyph-en-us.pat.txt)
ExceptionSourcecadenaNoRuta o URL al archivo de excepciones de guionización (p. ej., hyph-en-us.hyp.txt)

Los archivos de patrones siguen el formato de guionización TeX mantenido por el proyecto tex-hyphen en GitHub. Cada idioma tiene dos archivos en el repositorio: hyph-{lang}.pat.txt para reglas de patrones y hyph-{lang}.hyp.txt para la lista de excepciones. Al referenciar archivos alojados en GitHub, se requiere la URL de contenido sin procesar (que comienza con https://raw.githubusercontent.com/) — una URL de página estándar de GitHub devuelve HTML, no el texto de patrón.

¿Cómo anula la configuración de idioma incorporada la guionización personalizada?

El enum HyphenationLanguage en ChromePdfRenderOptions proporciona ajustes preestablecidos incorporados para inglés (EE.UU.), inglés (británico) y ruso. La propiedad CustomHyphenation tiene prioridad sobre este enum cuando ambos están configurados, siguiendo una cadena de prioridad clara:

  1. CustomHyphenation — si se establece con un PatternSource válido, se utilizan patrones personalizados
  2. HyphenationLanguage — si no se configuran patrones personalizados, se aplica el ajuste preestablecido de idioma incorporado
  3. Ninguno — si ninguno está configurado, no se produce guionización

¿Qué sucede cuando falla la carga del patrón personalizado?

Los errores durante la carga del patrón se registran pero no se lanzan excepciones. La operación de renderización continúa sin guionización en lugar de fallar. Si también se configura un valor de HyphenationLanguage, el renderizador recurre a ese ajuste preestablecido incorporado.

Este comportamiento de fallo silencioso es una decisión de diseño deliberada para entornos de producción. Un tiempo de espera de red al buscar un archivo de patrón remoto, una ruta de archivo no válida, un fallo de resolución DNS o contenido de patrón mal formado no bloquearán la canalización de renderización. El PDF aún se genera — solo carece de divisiones de palabras guionadas.

El intercambio es la visibilidad. Un archivo de patrón incorrecto o una URL inaccesible en la primera carga afectará silenciosamente cada renderización subsiguiente que utilice esos mismos valores de origen (ya que el almacenamiento en caché almacena también el estado de fallo). La recomendación es validar los archivos de patrones y confirmar el acceso a la red a las URL remotas durante el inicio de la aplicación o las verificaciones de despliegue CI/CD — no en el momento de renderización.