IRONSOFTWAREHOME

Jak dodać własne myślniki do generowania PDF w C#

Curtis Chau
Curtis Chau
Updated: 31 marca 2026

Własne myślniki w generowaniu PDF w C# pomagają naprawić niewygodne rozmieszczenie, przepełnienie słów i słabe łamanie tekstu w wąskich kolumnach, fakturach, kontraktach i wielojęzycznych raportach. Gdy renderer PDF nie stosuje odpowiednich wzorców myślników, justowany tekst może pozostawić duże luki lub źle się łamać na liniach.

W IronPDF myślniki są obsługiwane podczas renderowania HTML do PDF przez silnik Chromium, a nie przez model dokumentu w stylu Word. Właściwość CSS hyphens: auto pozwala rendererowi łamać słowa na poprawnych granicach sylab, a IronPDF stosuje to zachowanie podczas generacji PDF. Właścowość CustomHyphenation w ChromePdfRenderOptions kontroluje, które wzorce dywizji są używane.

Pliki wzorców używają formatu TeX i mogą być ładowane z lokalnej ścieżki pliku lub zdalnego URL. To umożliwia definiowanie własnych reguł myślników dla różnych języków i układów dokumentów z większą kontrolą nad łamaniem słów w finalnym PDF.

Ten przewodnik wyjaśnia, jak używać API CustomHyphenationDefinitions w C#, w tym lokalne i zdalne ładowanie wzorców, zachowanie zapasowe, ograniczenia, obsługę błędów i buforowanie.


NuGetZainstaluj za pomocą NuGet

PM > Install-Package IronPdf

Install IronPDF by running the command above in the NuGet Package Manager Console, or search for the package in the NuGet Package Manager.
Szybki start
  1. 1Install IronPDF with NuGet Package Manager

    PM > Install-Package IronPdf

  2. 2Skopiuj i uruchom ten fragment kodu.

    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#
  3. 3Wdrożenie do testowania w środowisku produkcyjnym

    Rozpocznij używanie IronPDF w swoim projekcie już dziś z darmową wersją próbną
    arrow pointer

Minimalny Przebieg

  1. Zainstaluj pakiet IronPDF NuGet
  2. Utwórz instancję renderer
  3. Ustal renderer.CustomHyphenation na nowy CustomHyphenationDefinitions ze ścieżką PatternSource lub URL
  4. Dodaj hyphens w CSS zawartości HTML
  5. Wywołaj renderer.RenderHtmlAsPdf() i zapisz wynik

Jak Działa Własne Łamanie Myślników w Renderowaniu PDF?

Klasa CustomHyphenationDefinitions definiuje, skąd IronPDF ładuje zasady dywizji podczas procesu renderowania. Silnik Chromium odczytuje te wzorce i stosuje je, gdy zasada CSS hyphens jest obecna na elemencie HTML.

Co To Jest Klasa CustomHyphenationDefinitions?

Klasa udostępnia dwie właściwości:

Tabela 1: Właściwości CustomHyphenationDefinitions
WłaściwośćTypWymaganeOpis
PatternSourceciąg_znakówTakŚcieżka lub URL do pliku wzorców myślników (np. hyph-en-us.pat.txt)
Źródło wyjątkuciąg_znakówNieŚcieżka lub URL do pliku wyjątków myślników (np. hyph-en-us.hyp.txt)

Pliki wzorców stosują format hyphenacji TeX utrzymywany przez projekt tex-hyphen na GitHub. Każdy język ma dwa pliki w repozytorium: hyph-{lang}.pat.txt dla zasad wzorców i hyph-{lang}.hyp.txt dla listy wyjątków. Podczas odwoływania się do plików umieszczonych na GitHub, wymagany jest URL surowej zawartości (zaczynający się od https://raw.githubusercontent.com/) — standardowy URL strony GitHub zwraca HTML, a nie tekst wzorca.

Co powoduje, że niestandardowe podziały zastępują wbudowane ustawienia języka?

Enum PdfHyphenationLanguage i jego HyphenationLanguage na ChromePdfRenderOptions udostępniają wbudowane presety dla angielskiego (US), angielskiego (brytyjskiego) i rosyjskiego. Właściwość CustomHyphenation ma priorytet nad tym enum, gdy oba są ustawione, postępując za wyraźnym łańcuchem priorytetu:

  1. CustomHyphenation — jeśli ustawione z prawidłowym PatternSource, używane są niestandardowe wzorce
  2. HyphenationLanguage — jeśli nie skonfigurowano własnych wzorców, zastosowano wbudowane ustawienie języka
  3. Niene — jeśli żaden z nich nie jest ustawiony, brak myślników

Co Się Dzieje, Gdy Ładowanie Własnych Wzorców Się Nie Powoduje?

Błędy podczas ładowania wzorców są rejestrowane, ale nie rzucają wyjątków. Operacja renderowania kontynuuje bez myślników zamiast się niepowodzenia. Jeśli wartość HyphenationLanguage również jest skonfigurowana, renderer przechodzi na ten wbudowany preset.

To zachowanie niewidocznie awarii jest celowym wyborem projektowym dla środowisk produkcyjnych. Upłynięcie czasu sieciowego podczas pobierania zdalnego pliku wzorców, nieprawidłowa ścieżka pliku, awaria rozwiązywania DNS czy błędnie sformułowana zawartość wzorca nie spowodują awarii linii renderowania. PDF nadal jest generowany - po prostu brakuje w nim łamanych słów.

Koszt to widoczność. Zły plik wzorcowy lub nieosiągalny URL przy pierwszym ładowaniu będzie cicho wpływał na każde kolejne renderowanie z użyciem tych samych wartości źródłowych (ponieważ pamięć podręczna przechowuje również stan błędu). Zaleceniem jest weryfikacja plików wzorcowych i potwierdzenie dostępu sieciowego do zdalnych URL-i podczas uruchamiania aplikacji lub kontroli wdrożenia CI/CD — nie podczas renderowania.


Jak można załadować pliki wzorcowe z zdalnego URL?

Ustawienie PatternSource na zdalny URL to najszybszy sposób na zastosowanie niestandardowej dywizji bez włączania plików do projektu. Następujący przykład ładuje U.S. Angielskie wzorce z repozytorium tex-hyphen i renderuje wyjustowany blok tekstu:

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");

Wynik

Renderowany PDF pokazuje wyjustowany akapit z czystymi końcami wyrazów na granicach sylab. Bez dzielenia wyrazów ten sam tekst generowałby duże przerwy między wyrazami lub zalewałby kolumnę.

Zarówno hyphens, jak i hyphenate-limit-chars deklaracje CSS są potrzebne dla kompatybilności z Chromium. Zasada hyphens sprawia, że dywizja jest najbardziej widoczna. Jeśli żadna deklaracja CSS nie jest obecna w docelowych elementach HTML, niestandardowe wzory są ładowane, ale nigdy nie stosowane.

Zwróć uwagę: URL musi wskazywać na surową treść tekstową. Standardowy URL GitHub jak https://github.com/hyphenation/tex-hyphen/blob/master/... zwraca powłokę strony HTML, która nie przejdzie walidacji wzorców. Użyj formy https://raw.githubusercontent.com/..., lub kliknij przycisk "Raw" na GitHub, aby uzyskać poprawny URL.

Jakie są ograniczenia źródeł zdalnych?

Tabela 2: Ograniczenia URL-ów zdalnych
OgraniczenieWartość
ProtokołyHTTP i HTTPS (zalecane HTTPS)
Dozwolone typy treścitext/plain, application/octet-stream
Maksymalny rozmiar odpowiedzi5 MB
Przekroczono limit czasu żądania10 sekund
BezpieczeństwoŻądania do prywatnych/lokalnych adresów IP (10.x.x.x, 192.168.x.x, localhost) są blokowane, aby zapobiec atakom SSRF
Odrzucona treśćPliki binarne, pliki z zerowymi bajtami, pliki zawierające tagi <script>

Kontenery i środowiska chmurowe (Docker, Azure, AWS) muszą mieć wyjściowy dostęp HTTP do hosta pliku wzorcowego, aby zdalne ładowanie powiodło się.


Moją ulubioną biblioteką tego typu jest IronPDF. Umożliwia ona szybkie i efektywne manipulowanie plikami PDF. Posiada także wiele cennych funkcji, takich jak eksport do formatu PDF/A i cyfrowe podpisywanie dokumentów PDF.

Milan Jovanovic

Microsoft MVP

Zobacz studium przypadku

IronOCR pozwala nam oszczędzić 40 000 USD rocznie na ręcznym przetwarzaniu, jednocześnie zwiększając produktywność i uwalniając zasoby do zadań o wysokim wpływie. Gorąco polecam.

Brent Matzelle

Dyrektor technologiczny, OPYN

Zobacz studium przypadku

IronSuite odgrywa kluczową rolę w naszej działalności. Są to narzędzia zwiększające wydajność w całej firmie, w tym tworzenie planów pięter i poprawa zarządzania zapasami.

David Jones

Główny inżynier oprogramowania, Agorus Build

Zobacz studium przypadku

Jak można załadować pliki wzorcowe z lokalnych plików?

Dla środowisk, gdzie dostęp do zewnętrznej sieci jest ograniczony lub gdzie preferowane jest wiązanie w czasie budowy, PatternSource akceptuje również lokalną ścieżkę systemu plików:

Zwróć uwagę: Pliki wzorcowe muszą istnieć na dysku przed uruchomieniem. Pobierz hyph-en-us.pat.txt i hyph-en-us.hyp.txt z repozytorium tex-hyphen i umieść je w ścieżce referowanej przez Twój kod.
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");

Wynik

Jak można zobaczyć poniżej, długie wyrazy, które w przeciwnym razie przepełniłyby się lub tworzyłyby nadmierne odstępy, są automatycznie łamane na granicach sylab. Silnik dzieli wyrazy tylko tam, gdzie to potrzebne — wyrazy, które pasują czysto do linii, pozostają całe.

Zmiana na inny język wymaga tylko zmiany ścieżek plików:

// 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"
};

To sprawia, że CustomHyphenation jest szczególnie użyteczne dla języków nie objętych wbudowanym enum PdfHyphenationLanguage, który obecnie wspiera tylko angielski (US), angielski (brytyjski) i rosyjski.

Jakie są ograniczenia lokalnych plików?

Tabela 3: Ograniczenia lokalnych plików
OgraniczenieWartość
Dozwolone rozszerzenia.txt, .pat
Maksymalny rozmiar pliku5 MB
KodowanieUTF-8
Zasady treściTylko prawidłowe wzory dzielenia wyrazów — bez komentarzy, metadanych, nagłówków, dyrektyw TeX lub notacji kodowania
Odrzucona treśćPliki binarne, pliki z zerowymi bajtami, pliki zawierające tagi <script>

Jak pamięć podręczna wpływa na wydajność w przetwarzaniu wsadowym?

Niestandardowe wzorce dywizji są buforowane w pamięci po pierwszym załadowaniu, kluczowane przez wartości PatternSource i ExceptionSource. Kolejne renderowanie, które odnosi się do tych samych ścieżek źródłowych lub URL, ponownie wykorzystuje składowane wzorce bez ponownego pobierania lub ponownego odczytywania plików.

To zachowanie ma dwa praktyczne implikacje dla pracy z dużą ilością renderowania PDF:

Wydajność: Pierwsze renderowanie ponosi koszt I/O (żądanie sieciowe lub odczyt dysku). Każde kolejne renderowanie jest efektywnie wolne z perspektywy ładowania wzorców. Dla zadań przetwarzania partii generujących setki PDF z tą samą konfiguracją dzielenia wyrazów, narzut jest znikomy.

Cisza niepowodzenia: Ponieważ błędy podczas ładowania wzorców nie są zgłaszane jako wyjątki, a renderer kontynuuje bez dzielenia wyrazów, zły plik wzorcowy lub niepowodzenie sieci na pierwszym załadunku pozostaną bezgłośne w całej partii. Każde kolejne renderowanie również będzie pozbawione dzielenia wyrazów, bez dodatkowych sygnałów o błędzie. Waliduj pliki wzorcowe i potwierdzaj dostępność URL podczas uruchamiania aplikacji lub wdrożenia — nie podczas renderowania.

Tożsamość klucza bufora: Klucz bufora to dokładna wartość ciągu PatternSource (i ExceptionSource, jeśli ustawione). Dwa instancje renderera wskazujące na ten sam URL lub ścieżkę do pliku dzielą te same składowane wzory. Zmiana URL-u — nawet na inną wersję tego samego pliku — wymusza nowe ładowanie.

Przeprowadź wstępną walidację zawartości pliku przed wdrożeniem produkcyjnym. Pliki wzorcowe muszą zawierać tylko prawidłowy tekst dzielenia wyrazów. Obecność komentarzy, dyrektyw TeX, deklaracji kodowania lub jakiejkolwiek treści niebędącej wzorcem powoduje, że integracja nie powiedzie się. Repozytorium tex-hyphen dostarcza z góry przygotowane czyste pliki wzorcowe dla dziesiątek języków.

HTTPS jest zalecane dla zdalnych źródeł wzorców. HTTP jest obsługiwane, ale nie zapewnia ochrony warstwy transportowej dla treści pliku.


Jakie są kolejne kroki?

Właściwość CustomHyphenation na ChromePdfRenderOptions daje bezpośrednią kontrolę nad zachowaniem łamania słów dla każdego języka obsługiwanego przez plik wzorca TeX — sięgając poza trzy wbudowane presety dostępne przez PdfHyphenationLanguage. Pliki wzorców ładują się z zdalnych URL lub lokalnych ścieżek, są buforowane w pamięci po pierwszym użyciu, i wracają do ustawienia HyphenationLanguage, jeśli ładowanie się nie powiedzie. Błędy są logowane, ale nigdy nie zgłaszane, więc walidacja wzorów powinna nastąpić podczas wdrożenia, a nie podczas renderowania.

Dla konfiguracji dotyczącej renderowania w IronPDF patrz:

Uzyskaj 30-dniową bezpłatną wersję próbną IronPDF, aby przetestować niestandardowe dzielenie wyrazów w żywym projekcie, lub zobacz opcje licencjonowania dla wdrożenia produkcyjnego.

ChromePdfRenderer PatternSource CustomHyphenationDefinitions string hyphens: auto RenderHtmlAsPdf CustomHyphenationDefinitions hyphens: auto HyphenationLanguage ChromePdfRenderOptions hyph-en-us.pat.txt -webkit-hyphens: auto text-align: justify PdfHyphenationLanguage ChromePdfRenderOptions

Często Zadawane Pytania

Jak mogę wdrożyć niestandardowy podział wyrazów w generowaniu PDFów przy użyciu C#?

Możesz wdrożyć niestandardowy podział wyrazów w generowaniu PDFów przy użyciu IronPDF, ładując wzorce dzielenia wyrazów TeX z adresów URL lub plików lokalnych. To pozwala kontrolować łamanie wyrazów podczas generowania PDFów w C#.

Czym są wzorce dzielenia wyrazów TeX i jak są używane w IronPDF?

Wzorce dzielenia wyrazów TeX to zestawy zasad do dzielenia wyrazów w odpowiednich miejscach. IronPDF pozwala ładować te wzorce do zarządzania, jak słowa są dzielone w generowanych PDFach.

Czy mogę ładować wzorce dzielenia wyrazów z adresu URL w IronPDF?

Tak, IronPDF wspiera ładowanie wzorców dzielenia wyrazów bezpośrednio z adresów URL, umożliwiając dynamiczną i elastyczną konfigurację łamania wyrazów w projektach C# PDF.

Czy można używać lokalnych plików dla wzorców dzielenia wyrazów z IronPDF?

Absolutnie, IronPDF pozwala ładować niestandardowe wzorce dzielenia wyrazów z lokalnych plików, dając precyzyjną kontrolę nad podziałem wyrazów w PDFach.

Jakie są ograniczenia przy używaniu niestandardowego podziału wyrazów w IronPDF?

Podczas używania niestandardowego podziału wyrazów w IronPDF, musisz upewnić się, że wzorce są poprawnie sformatowane i zgodne z zamierzonym językiem oraz wymaganiami układu dokumentu.

Dlaczego potrzebowałbym niestandardowego podziału wyrazów w moich dokumentach PDF?

Niestandardowy podział wyrazów jest przydatny do poprawy czytelności i zapewnienia spójnego formatowania dokumentów PDF, zwłaszcza gdy pracujemy ze złożonymi podziałami wyrazów specyficznymi dla języka.

Czy IronPDF dostarcza przykłady kodu do wdrożenia niestandardowego podziału wyrazów?

Tak, IronPDF dostarcza przykłady kodu, które pomogą wdrożyć niestandardowy podział wyrazów w projektach C#, ułatwiając integrację tej funkcji z procesem generowania PDFów.

Jak niestandardowy podział wyrazów poprawia generowanie PDFów?

Niestandardowy podział wyrazów poprawia generowanie PDFów, pozwalając na precyzyjną kontrolę nad łamaniem wyrazów, co poprawia wygląd i czytelność dokumentu w różnych językach i formatach.

Curtis Chau
Autor tekstów technicznych

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

...
Czytaj więcej

Gotowy, aby rozpocząć?

Nuget Downloads 20,667,543Wersja:2026.7właśnie wydany

Otrzymaj swój darmowy Klucz Próbny na 30 dni natychmiast.
Nie wymaga karty kredytowej ani tworzenia konta
Biblioteka C# NuGet dla plików PDF
Zainstaluj za pomocą NuGet

Wersja: 2026.7

PM > Install-Package IronPdf
nuget.org/packages/IronPdf/
  1. W Eksploratorze Rozwiązań, kliknij prawym przyciskiem Myszy na Odwołania, Zarządzaj pakietami NuGet
  2. Wybierz opcję Przeglądaj i wyszukaj „IronPdf”
  3. Wybierz pakiet i zainstaluj
DLL PDF dla C#
Pobierz DLL

Wersja: 2026.7

Pobierz teraz

lub pobierz instalator Windows tutaj.

  1. Pobierz i rozpakuj IronPDF do lokalizacji takiej jak ~/Libs w katalogu Solution
  2. W Eksploratorze rozwiązań programu Visual Studio kliknij prawym przyciskiem myszy opcję Odwołania. Wybierz opcję Przeglądaj, „IronPdf.dll”

Licencje od 749 USD

Key in blue circle

Uzyskaj natychmiast swój darmowy 30-dniowy Klucz Testowy.

Brak ograniczeń. 100% dostępności. Bez karty kredytowej.

bullet_checkedNie wymaga karty kredytowej ani tworzenia kontaBrak ograniczeń. 100% dostępności. Bez karty kredytowej.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
Zarezerwuj swoje darmowe Demo na żywo
Booking Badge

Zaufane przez miliony inżynierów na całym świecie

Logotypy klientów Iron Software
Otrzymaj swoje Konsultacja Bez Zobowiązań
Wypełnij poniższy formularz lub wyślij e-mail na sales@ironsoftware.com
Twoje dane zawsze będą utrzymywane w tajemnicy.
Zaufane przez miliony inżynierów na całym świecie
Logotypy klientów Iron Software
Otrzymaj swój darmowy Klucz Próbny na 30 dni natychmiast.
Nie wymaga karty kredytowej ani tworzenia konta