Comment ajouter une césure personnalisée à la génération de PDF en C#
La césure personnalisée dans la génération de PDF en C# aide à corriger l'espacement maladroit, le débordement de mots et le mauvais retour de texte dans des colonnes étroites, des factures, des contrats et des rapports multilingues. Lorsque le moteur de rendu PDF n'applique pas les motifs de césure corrects, le texte justifié peut laisser de grands espaces ou être mal coupé en travers des lignes.
Dans IronPDF, la césure est gérée pendant le rendu HTML vers PDF via le moteur Chromium, et non via un modèle d'objet document de type Word. La propriété CSS hyphens: auto permet au moteur de découper les mots à des frontières de syllabes valides, et IronPDF applique ce comportement lors de la génération de PDF. La propriété CustomHyphenation dans ChromePdfRenderOptions contrôle quels motifs de césure sont utilisés.
Les fichiers de motifs utilisent le format TeX et peuvent être chargés soit depuis un chemin de fichier local, soit depuis une URL distante. Cela permet de définir des règles de césure personnalisées pour différentes langues et dispositions de documents avec plus de contrôle sur les césures de mots dans le PDF final.
Ce guide explique comment utiliser l'API CustomHyphenationDefinitions en C#, y compris le chargement de motifs locaux et distants, le comportement de repli, les limitations, la gestion des erreurs et la mise en cache.
Installer avec NuGet-
1Install IronPDF with NuGet Package Manager
-
2Copiez et exécutez cet extrait de code.
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# -
3Déployez pour tester sur votre environnement de production.
Commencez à utiliser IronPDF dans votre projet dès aujourd'hui avec un essai gratuit
Flux de travail minimal
- Installez le package NuGet IronPDF
- Créez une instance de
renderer - Définissez
renderer.CustomHyphenationsur un nouveauCustomHyphenationDefinitionsavec un chemin ou une URLPatternSource - Incluez
hyphensdans le CSS du contenu HTML - Appelez
renderer.RenderHtmlAsPdf()et enregistrez le résultat
Comment fonctionne la césure personnalisée dans le rendu PDF ?
La classe CustomHyphenationDefinitions définit d'où IronPDF charge les règles de césure durant le processus de rendu. Le moteur Chromium lit ces motifs et les applique lorsque la règle CSS hyphens est présente sur un élément HTML.
Qu'est-ce que la classe CustomHyphenationDefinitions ?
La classe expose deux propriétés :
| Propriété | Type de texte | Requis | Description du projet |
|---|---|---|---|
PatternSource | chaîne | Oui | Chemin ou URL vers le fichier de motifs de césure (par exemple, hyph-en-us.pat.txt) |
ExceptionSource | chaîne | Non | Chemin ou URL vers le fichier d'exceptions de césure (par exemple, hyph-en-us.hyp.txt) |
Les fichiers de motifs suivent le format de césure TeX maintenu par le projet tex-hyphen sur GitHub. Chaque langue possède deux fichiers dans le dépôt : hyph-{lang}.pat.txt pour les règles de motifs et hyph-{lang}.hyp.txt pour la liste d'exceptions. Lors de la référence aux fichiers hébergés sur GitHub, l'URL du contenu brut (commençant par https://raw.githubusercontent.com/) est requise — une URL de page GitHub standard retourne du HTML, pas le texte de motifs.
Que fait la césure personnalisée en outrepassant le paramètre de langue intégré ?
L'énum PdfHyphenationLanguage et son HyphenationLanguage sur ChromePdfRenderOptions fournit des préréglages intégrés pour l'anglais (US), l'anglais (britannique) et le russe. La propriété CustomHyphenation a priorité sur cet énum si les deux sont définis, en suivant une chaîne de priorités claire :
- CustomHyphenation — si défini avec un
PatternSourcevalide, des motifs personnalisés sont utilisés - HyphenationLanguage — si aucun motif personnalisé n'est configuré, le préréglage de langue intégré s'applique
- Aucun — si aucun n'est défini, aucune césure n'est appliquée
Que se passe-t-il lorsque le chargement de motifs personnalisés échoue ?
Les erreurs lors du chargement des motifs sont enregistrées mais ne déclenchent pas d'exceptions. L'opération de rendu continue sans césure plutôt que d'échouer. Si une valeur HyphenationLanguage est également configurée, le moteur de rendu revient à ce préréglage intégré.
Ce comportement d'échec silencieux est un choix de conception délibéré pour les environnements de production. Un délai réseau lors de l'obtention d'un fichier de motif distant, un chemin de fichier invalide, un échec de résolution DNS, ou un contenu de motif mal formé ne fera pas planter le pipeline de rendu. Le PDF est toujours généré — il manque simplement les césures.
Le compromis est la visibilité. Un mauvais fichier de motif ou une URL inatteignable lors du premier chargement affectera silencieusement chaque rendu ultérieur utilisant les mêmes valeurs de source (car la mise en cache enregistre aussi l'état d'échec). La recommandation est de valider les fichiers de motifs et de confirmer l'accès réseau aux URL distantes lors du démarrage de l'application ou des vérifications de déploiement CI/CD — pas au moment du rendu.
Comment les fichiers de motifs peuvent-ils être chargés à partir d'une URL distante ?
Pointer PatternSource vers une URL distante est le moyen le plus rapide d'appliquer une césure personnalisée sans intégrer de fichiers dans le projet. L'exemple suivant charge les motifs. Les motifs d'anglais des États-Unis du dépôt tex-hyphen et rend un bloc de texte justifié :
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")Sortie
Le PDF rendu montre le paragraphe justifié avec des césures nettes aux limites de syllabes. Sans césure, ce même texte produirait de grands espaces entre les mots ou déborderait de la colonne.
Les déclarations CSS hyphens et hyphenate-limit-chars sont nécessaires pour la compatibilité Chromium. La règle hyphens rend la césure la plus visible. Si aucune déclaration CSS n'est présente sur les éléments HTML cibles, les motifs personnalisés sont chargés mais jamais appliqués.
https://github.com/hyphenation/tex-hyphen/blob/master/... retourne un emballage de page HTML, ce qui échouera lors de la validation des motifs. Utilisez le formulaire https://raw.githubusercontent.com/..., ou cliquez sur le bouton 'Raw' sur GitHub pour obtenir l'URL correcte.Quelles sont les contraintes source distantes ?
| Contrainte | Valeur |
|---|---|
| Protocoles | HTTP et HTTPS (HTTPS recommandé) |
| Type de textes de contenu autorisés | text/plain, application/octet-stream |
| Taille de réponse maximale | 5 Mo |
| Délai d'attente dépassé | 10 secondes |
| Sécurité | Les requêtes vers des IP privées/locales (10.x.x.x, 192.168.x.x, localhost) sont bloquées pour éviter les attaques SSRF |
| Contenu rejeté | Fichiers binaires, fichiers avec octets nuls, fichiers contenant des balises <script> |
Les containers et environnements cloud (Docker, Azure, AWS) doivent avoir un accès HTTPS sortant à l'hôte du fichier de motifs pour que le chargement distant réussisse.
Ma bibliothèque préférée de ce genre est IronPDF. Elle permet une manipulation rapide et efficace des fichiers PDF. Elle dispose également de nombreuses fonctionnalités précieuses, comme l'exportation au format PDF/A et la signature numérique des documents PDF.
IronOCR signifie que nous pouvons économiser 40 000 $ par an grâce au traitement manuel, tout en améliorant la productivité et en libérant des ressources pour des tâches à fort impact. Je le recommande vivement.
Iron Suite joue un rôle crucial dans nos opérations. Ce sont des outils qui augmentent l'efficacité de l'entreprise, y compris la création de plans d'étage et l'amélioration de la gestion des stocks.
Comment les fichiers de motifs peuvent-ils être chargés à partir de fichiers locaux ?
Pour les environnements où l'accès au réseau externe est restreint ou où un regroupement au moment de la construction est préférable, PatternSource accepte également un chemin de système de fichiers local :
hyph-en-us.pat.txt et hyph-en-us.hyp.txt depuis le dépôt tex-hyphen et placez-les dans le chemin référencé par votre code.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")Sortie
Comme indiqué ci-dessous, les longs mots qui autrement déborderaient ou créeraient un espacement excessif sont automatiquement coupés aux limites de syllabes. Le moteur ne césure que là où c'est nécessaire — les mots qui s'adaptent proprement sur une ligne sont laissés entiers.
Changer de langue nécessite seulement un changement de chemins de fichiers :
// 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"
}Cela rend CustomHyphenation particulièrement utile pour les langues non couvertes par l'énum intégré PdfHyphenationLanguage, qui prend actuellement en charge uniquement l'anglais (US), l'anglais (britannique) et le russe.
Quelles sont les contraintes des fichiers locaux ?
| Contrainte | Valeur |
|---|---|
| Extensions autorisées | .txt, .pat |
| Taille maximale de fichier | 5 Mo |
| Encodage | UTF-8 |
| Règles de contenu | Motifs de césure valides uniquement — pas de commentaires, de métadonnées, d'en-têtes, de directives TeX ou de notes d'encodage |
| Contenu rejeté | Fichiers binaires, fichiers avec octets nuls, fichiers contenant des balises <script> |
Comment la mise en cache affecte-t-elle les performances dans le rendu par lots ?
Les motifs de césure personnalisés sont mis en cache en mémoire après le premier chargement, clés par les valeurs PatternSource et ExceptionSource. Les rendus suivants qui se réfèrent aux mêmes chemins source ou URL réutilisent les motifs mis en cache sans retélécharger ni relire les fichiers.
Ce comportement a deux implications pratiques pour les flux de travail de rendu PDF à haut volume :
Performance : Le premier rendu entraîne le coût d'E/S (requête réseau ou lecture disque). Chaque rendu après cela est effectivement gratuit du point de vue du chargement de motifs. Pour les travaux par lots générant des centaines de PDF avec la même configuration de césure, la surcharge est négligeable.
Persistance de l'échec silencieux : Parce que les erreurs lors du chargement des motifs ne déclenchent pas d'exceptions et que le moteur de rendu continue sans césure, un mauvais fichier de motif ou un échec réseau lors du premier chargement restera silencieusement persistant tout au long du lot. Chaque rendu suivant manquera aussi de césure, sans signal d'erreur supplémentaire. Valider les fichiers de motifs et confirmer l'accessibilité des URL lors du démarrage de l'application ou du déploiement — pas au moment du rendu.
Identité de la clé de mise en cache : La clé de mise en cache est la valeur de chaîne exacte de PatternSource (et ExceptionSource si défini). Deux instances de moteur de rendu pointant vers la même URL ou chemin de fichier partagent les mêmes motifs mis en cache. Changer l'URL — même vers une version différente du même fichier — force un nouveau chargement.
Valider le contenu du fichier avant le déploiement en production. Les fichiers de motifs doivent contenir uniquement un texte de césure valide. La présence de commentaires, de directives TeX, de déclarations d'encodage ou de tout contenu non lié aux motifs fait échouer l'intégration. Le dépôt tex-hyphen fournit des fichiers de motifs propres et préconstruits pour des dizaines de langues.
HTTPS est recommandé pour les sources de motifs distants. HTTP est pris en charge mais n'offre aucune protection de couche de transport pour le contenu du fichier.
Quelles sont les prochaines étapes?
La propriété CustomHyphenation sur ChromePdfRenderOptions donne le contrôle direct du comportement de coupure de mots pour toute langue prise en charge par un fichier de motifs TeX — s'étendant au-delà des trois préréglages intégrés disponibles via PdfHyphenationLanguage. Les fichiers de motifs se chargent à partir d'URLs distantes ou de chemins locaux, sont mis en cache en mémoire après la première utilisation, et reviennent à la configuration HyphenationLanguage si le chargement échoue. Les erreurs sont enregistrées mais jamais déclenchées, donc la validation des motifs doit se faire lors du déploiement plutôt qu'au moment du rendu.
Pour la configuration liée au rendu IronPDF, voir :
- Référence de l'API
ChromePdfRenderOptionspour toutes les options de rendu disponibles - Énum
PdfHyphenationLanguagepour les préréglages de langue intégrés - Tutoriel de rendu HTML vers PDF pour le pipeline complet de rendu HTML
- Options de rendu - comment faire pour la configuration d'autres options de ChromePdfRenderOptions
- Aperçu des fonctionnalités d'IronPDF pour l'ensemble complet des capacités de génération et manipulation de PDF
Obtenez un essai gratuit de 30 jours d'IronPDF pour tester la césure personnalisée dans un projet en direct, ou consultez les options de licence pour le déploiement en production.
ChromePdfRendererPatternSourceCustomHyphenationDefinitionsstringhyphens: auto``RenderHtmlAsPdfCustomHyphenationDefinitionshyphens: autoHyphenationLanguageChromePdfRenderOptionshyph-en-us.pat.txt-webkit-hyphens: auto``text-align: justifyPdfHyphenationLanguageChromePdfRenderOptions
Questions Fréquemment Posées
Comment puis-je implémenter une césure personnalisée dans la génération de PDF en utilisant C# ?
Vous pouvez implémenter une césure personnalisée dans la génération de PDF en utilisant IronPDF en chargeant les modèles de césure TeX à partir d'URLs ou de fichiers locaux. Cela vous permet de contrôler la séparation des mots lors de la génération de PDF en C#.
Qu'est-ce que les modèles de césure TeX et comment sont-ils utilisés dans IronPDF ?
Les modèles de césure TeX sont des ensembles de règles pour diviser les mots aux points de césure appropriés. IronPDF vous permet de charger ces modèles pour gérer comment les mots sont césurés dans vos PDF générés.
Puis-je charger des modèles de césure à partir d'une URL dans IronPDF ?
Oui, IronPDF prend en charge le chargement des modèles de césure directement depuis des URLs, permettant des configurations dynamiques et flexibles de séparation des mots pour vos projets PDF en C#.
Est-il possible d'utiliser des fichiers locaux pour les modèles de césure avec IronPDF ?
Absolument, IronPDF vous permet de charger des modèles de césure personnalisés à partir de fichiers locaux, ce qui vous donne un contrôle précis sur la césure des mots dans vos PDF.
Quelles sont les contraintes lors de l'utilisation de la césure personnalisée dans IronPDF ?
Lorsque vous utilisez la césure personnalisée dans IronPDF, vous devez vous assurer que les modèles sont correctement formatés et qu'ils correspondent aux exigences linguistiques et de mise en page du document.
Pourquoi aurais-je besoin de césure personnalisée dans mes documents PDF ?
La césure personnalisée est utile pour améliorer la lisibilité et assurer une mise en forme cohérente dans les documents PDF, surtout lorsqu'il s'agit de césures de mots spécifiques à une langue complexe.
IronPDF fournit-il des exemples de code pour implémenter la césure personnalisée ?
Oui, IronPDF fournit des exemples de code pour vous aider à implémenter la césure personnalisée dans vos projets C#, facilitant ainsi l'intégration de cette fonctionnalité dans votre processus de génération de PDF.
Comment la césure personnalisée améliore-t-elle la génération de PDF ?
La césure personnalisée améliore la génération de PDF en permettant un contrôle précis des séparations de mots, ce qui améliore l'apparence et la lisibilité du document dans différentes langues et formats.
Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.
