Jak dodać własne myślniki do generowania PDF w C#
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.
-
1Install IronPDF with NuGet Package Manager
-
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# -
3Wdrożenie do testowania w środowisku produkcyjnym
Rozpocznij używanie IronPDF w swoim projekcie już dziś z darmową wersją próbną
Minimalny Przebieg
- Zainstaluj pakiet IronPDF NuGet
- Utwórz instancję
renderer - Ustal
renderer.CustomHyphenationna nowyCustomHyphenationDefinitionsze ścieżkąPatternSourcelub URL - Dodaj
hyphensw CSS zawartości HTML - 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:
| Właściwość | Typ | Wymagane | Opis |
|---|---|---|---|
PatternSource | ciąg_znaków | Tak | Ścieżka lub URL do pliku wzorców myślników (np. hyph-en-us.pat.txt) |
Źródło wyjątku | ciąg_znaków | Nie | Ś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:
- CustomHyphenation — jeśli ustawione z prawidłowym
PatternSource, używane są niestandardowe wzorce - HyphenationLanguage — jeśli nie skonfigurowano własnych wzorców, zastosowano wbudowane ustawienie języka
- 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");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")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.
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?
| Ograniczenie | Wartość |
|---|---|
| Protokoły | HTTP i HTTPS (zalecane HTTPS) |
| Dozwolone typy treści | text/plain, application/octet-stream |
| Maksymalny rozmiar odpowiedzi | 5 MB |
| Przekroczono limit czasu żądania | 10 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ę.
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.
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:
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");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")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"
};' 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"
}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?
| Ograniczenie | Wartość |
|---|---|
| Dozwolone rozszerzenia | .txt, .pat |
| Maksymalny rozmiar pliku | 5 MB |
| Kodowanie | UTF-8 |
| Zasady treści | Tylko 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:
- Dokumentacja API
ChromePdfRenderOptionsdla wszystkich dostępnych opcji renderowania - Enum
PdfHyphenationLanguagedla wbudowanych presety językowych - Samouczek HTML do PDF dla pełnego potoku renderowania HTML
- Jak używać opcji renderowania dla innych konfiguracji ChromePdfRenderOptions
- Przegląd funkcji IronPDF dla pełnego zestawu możliwości generowania i manipulacji PDF
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 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.