1. IronPDF
  2. Anleitungen
  3. Benutzerdefinierte Trennung

Wie man benutzerdefinierte Silbentrennung zur PDF-Erstellung in C# hinzufügt

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

Benutzerdefinierte Silbentrennung bei der PDF-Erstellung in C# hilft, ungleichmäßige Abstände, Wortüberläufe und schlechte Umbrüche in schmalen Spalten, Rechnungen, Verträgen und mehrsprachigen Berichten zu beheben. Wenn ein PDF-Renderer die richtigen Silbentrennungsregeln nicht anwendet, kann Blocksatz große Lücken hinterlassen oder schlecht über Zeilen umbrechen.

In IronPDF wird die Silbentrennung während des HTML-zu-PDF-Renderings über die Chromium-Engine gehandhabt, nicht über ein Word-ähnliches Dokument-Objekt-Modell. Die CSS-Eigenschaft hyphens: auto erlaubt es dem Renderer, Wörter an gültigen Silbengrenzen zu brechen, und IronPDF wendet dieses Verhalten bei der PDF-Erstellung an. Die Eigenschaft CustomHyphenation in ChromePdfRenderOptions steuert, welche Silbentrennungsregeln verwendet werden.

Musterdateien verwenden das TeX-Format und können entweder von einem lokalen Dateipfad oder einer entfernten URL geladen werden. Dies ermöglicht es, benutzerdefinierte Silbentrennungsregeln für verschiedene Sprachen und Dokumentlayouts mit mehr Kontrolle über Worttrennungen im finalen PDF zu definieren.

Diese Anleitung erklärt, wie Sie die CustomHyphenationDefinitions API in C# verwenden, einschließlich lokaler und entfernter Musterladungen, Ausweichverhalten, Einschränkungen, Fehlerbehandlung und Caching.

NuGet Mit NuGet installieren

PM >  Install-Package IronPdf

Schauen Sie sich IronPDF auf NuGet für eine schnelle Installation an. Mit über 10 Millionen Downloads transformiert es die PDF-Entwicklung mit C#. Sie können auch das DLL oder den Windows Installer herunterladen.

Schnellstart

  1. Installieren Sie IronPDF mit NuGet Package Manager

    PM > Install-Package IronPdf

  2. Kopieren Sie diesen Codeausschnitt und führen Sie ihn aus.

    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. Bereitstellen zum Testen in Ihrer Live-Umgebung

    Beginnen Sie noch heute, IronPDF in Ihrem Projekt zu verwenden, mit einer kostenlosen Testversion

    arrow pointer

Minimaler Arbeitsablauf

  1. Installieren Sie das IronPDF NuGet-Paket
  2. Erstellen Sie eine ChromePdfRenderer-Instanz
  3. Setzen Sie RenderingOptions.CustomHyphenation auf ein neues CustomHyphenationDefinitions mit einem PatternSource-Pfad oder einer URL
  4. Integrieren Sie hyphens: auto in den CSS-Inhalt des HTML
  5. Rufen Sie RenderHtmlAsPdf auf und speichern Sie das Ergebnis

Wie funktioniert benutzerdefinierte Silbentrennung im PDF-Rendering?

Die CustomHyphenationDefinitions-Klasse definiert, wo IronPDF Silbentrennungsregeln während des Renderprozesses laden soll. Die Chromium-Engine liest diese Muster und wendet sie an, wenn die CSS-Regel hyphens: auto auf einem HTML-Element vorhanden ist.

Was ist die Klasse CustomHyphenationDefinitions?

Die Klasse legt zwei Eigenschaften offen:

Tabelle 1: Eigenschaften von CustomHyphenationDefinitions
EigenschaftTypErforderlichBeschreibung
PatternSourceStringJaPfad oder URL zur Silbentrennungsmusterdokument (z. B. hyph-en-us.pat.txt)
ExceptionSourceStringNeinPfad oder URL zur Silbentrennungsausnahmedatei (z. B. hyph-en-us.hyp.txt)

Musterdateien folgen dem TeX-Silbentrennungsformat, das vom tex-hyphen-Projekt auf GitHub gepflegt wird. Jede Sprache hat zwei Dateien im Repository: hyph-{lang}.pat.txt für Musterregeln und hyph-{lang}.hyp.txt für die Ausnahmeliste. Wenn auf Dateien verwiesen wird, die auf GitHub gehostet werden, ist die rohe Inhalts-URL (beginnend mit https://raw.githubusercontent.com/) erforderlich — eine Standard-URL zu einer GitHub-Seite gibt HTML zurück, nicht das Musterdokument.

Wie überschreibt benutzerdefinierte Silbentrennung die integrierte Spracheinstellung?

Das HyphenationLanguage-Enum auf ChromePdfRenderOptions bietet eingebaute Voreinstellungen für Englisch (US), Englisch (Britisch) und Russisch. Die CustomHyphenation-Eigenschaft hat Vorrang vor diesem Enum, wenn beide gesetzt sind, indem sie einer klaren Prioritätskette folgt:

  1. CustomHyphenation — wenn mit einer gültigen PatternSource gesetzt, werden benutzerdefinierte Muster verwendet
  2. HyphenationLanguage — wenn keine benutzerdefinierten Muster konfiguriert sind, wird die eingebaute Spracheinstellung angewandt
  3. Neinne — wenn keines von beiden gesetzt ist, erfolgt keine Silbentrennung

Was passiert, wenn das Laden von benutzerdefinierten Mustern fehlschlägt?

Fehler beim Laden von Mustern werden protokolliert, aber keine Ausnahmen geworfen. Der Render-Vorgang wird ohne Silbentrennung fortgesetzt, anstatt zu fehlschlagen. Wenn auch ein Wert für HyphenationLanguage konfiguriert ist, greift der Renderer auf diese eingebaute Voreinstellung zurück.

Dieses stille Fehlverhalten ist eine bewusste Designentscheidung für Produktionsumgebungen. Eine Netzwerk-Zeitüberschreitung beim Abrufen einer entfernten Musterdokument, ein unzulässiger Dateipfad, ein DNS-Auflösungsfehler oder fehlerhafter Musterinhalt wird die Rendering-Pipeline nicht zum Absturz bringen. Das PDF wird dennoch erstellt — es fehlen nur die Silbentrennungen.

Der Kompromiss ist die Sichtbarkeit. Eine fehlerhafte Musterdokument oder eine unerreichbare URL beim ersten Laden beeinträchtigt stillschweigend jeden nachfolgenden Render-Vorgang unter Verwendung derselben Quellwerte (da das Caching auch den Fehlerzustand speichert). Die Empfehlung lautet, Musterdokumente zu validieren und den Netzwerkzugriff auf entfernte URLs während des Anwendungsstarts oder CI/CD-Bereitstellungsprüfungen zu bestätigen — nicht zur Renderzeit.

Wie können Musterdokumente von einer entfernten URL geladen werden?

Das Setzen von PatternSource auf eine entfernte URL ist der schnellste Weg, um benutzerdefinierte Silbentrennung anzuwenden, ohne Dateien in das Projekt einzubinden. Das folgende Beispiel lädt US-amerikanische Englisch-Muster aus dem tex-hyphen-Repository und rendert einen Blocksatz-Textblock:

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

Ausgabe

Das gerenderte PDF zeigt den Blocksatzabsatz mit sauberen Worttrennungen an Silbengrenzen. Ohne Silbentrennung würde derselbe Text große Wortzwischenräume erzeugen oder die Spalte überlaufen.

Sowohl hyphens: auto als auch -webkit-hyphens: auto CSS-Deklarationen sind für die Kompatibilität mit Chromium erforderlich. Die Regel text-align: justify macht Silbentrennung am sichtbarsten. Wenn keine CSS-Deklarationen auf den Ziel-HTML-Elementen vorhanden sind, werden die benutzerdefinierten Muster geladen, aber nicht angewendet.

Der URL muss auf rohe Textinhalte zeigen. Eine Standard-URL zu GitHub wie https://github.com/hyphenation/tex-hyphen/blob/master/... gibt eine HTML-Seitenumgebung zurück, die die Musterüberprüfung fehlschlagen lässt. Verwenden Sie die Form https://raw.githubusercontent.com/... oder klicken Sie auf die Schaltfläche "Raw" auf GitHub, um die richtige URL zu erhalten.

Was sind die Einschränkungen beim Entfernten Laden?

Tabelle 2: Einschränkungen bei entfernten URLs
EinschränkungWert
ProtokolleHTTP und HTTPS (HTTPS empfohlen)
Erlaubte Inhaltsartentext/plain, application/octet-stream
Maximale Antwortgröße5 MB
Zeitüberschreitung der Anfrage10 Sekunden
SicherheitAnfragen an private/lokale IPs (10.x.x.x, 192.168.x.x, localhost) werden blockiert um SSRF-Angriffe zu verhindern
Abgelehnter InhaltBinärdateien, Dateien mit Nullbytes, Dateien mit
Still Scrolling Icon

Scrollst du immer noch?

Sie brauchen schnell einen Beweis? PM > Install-Package IronPdf
Führen Sie eine Probe aus Sehen Sie zu, wie Ihr HTML-Code in eine PDF-Datei umgewandelt wird.

30-Tage-Testversion → Volles Produkt. Keine Grenzen. Keine Karte. Gratis testen

Iron Support Team

Wir sind 24 Stunden am Tag, 5 Tage die Woche online.
Chat
E-Mail
Rufen Sie mich an