1. IronPDF
  2. 방법
  3. 사용자 정의 하이픈 처리

C#에서 PDF 생성에 사용자 정의 하이픈 삽입하는 방법

아흐마드 소하일
아흐마드 소하일
업데이트됨:
This article was translated from English: Does it need improvement?
Translated
View the article in English

C# PDF 생성에서의 사용자 정의 하이픈 삽입은 좁은 열, 송장, 계약 및 다언어 보고서에서 어색한 간격, 단어 넘침, 부적절한 텍스트 줄 바꿈 등을 해결하는 데 도움이 됩니다. PDF 렌더러가 올바른 하이픈 패턴을 적용하지 않으면, 정렬된 텍스트가 큰 간격을 남기거나 줄을 넘어 부적절하게 구분될 수 있습니다.

IronPDF에서는 HTML에서 PDF로 렌더링할 때 Word 스타일의 문서 객체 모델을 사용하는 대신 Chromium 엔진을 통해 하이픈이 처리됩니다. CSS 속성인 hyphens: auto은 렌더러가 적절한 음절 경계에서 단어를 분할할 수 있도록 하며, IronPDF는 PDF 생성 시 해당 동작을 적용합니다. ChromePdfRenderOptions에서 속성 CustomHyphenation은 사용되는 하이픈 규칙을 제어합니다.

패턴 파일은 TeX 형식을 사용하며 로컬 파일 경로 또는 원격 URL에서 로드될 수 있습니다. 이로 인해 다양한 언어 및 문서 레이아웃에 맞춰 사용자 정의 하이픈 규칙을 정의할 수 있으며, 최종 PDF에서 더욱 세부적으로 단어 끊기를 제어할 수 있습니다.

이 가이드는 C#에서 API CustomHyphenationDefinitions를 사용하는 방법을 설명하며, 지역 및 원격 패턴 로딩, 대체 동작, 제한 사항, 오류 처리, 캐싱을 포함합니다.

!{--010011000100100101000010010100100100000101010010010110010101111101001110010101010001110100010101010100010111110100100101001110010100110101010001000001010011000100110001001100010111110100001001001100010011110100001101001011--}

빠른 시작

  1. NuGet 패키지 관리자를 사용하여 https://www.nuget.org/packages/IronPdf 설치하기

    PM > Install-Package IronPdf

  2. 다음 코드 조각을 복사하여 실행하세요.

    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. 실제 운영 환경에서 테스트할 수 있도록 배포하세요.

    무료 체험판으로 오늘 프로젝트에서 IronPDF 사용 시작하기

    arrow pointer

최소 워크플로우

  1. IronPDF NuGet 패키지 설치
  2. ChromePdfRenderer 인스턴스 생성
  3. PatternSource 경로 또는 URL과 함께 새 CustomHyphenationDefinitions로 RenderingOptions.CustomHyphenation 설정
  4. HTML 콘텐츠의 CSS에 hyphens: auto 포함
  5. RenderHtmlAsPdf를 호출하고 결과 저장

PDF 렌더링에서 사용자 정의 하이픈이 어떻게 작동하는가?

CustomHyphenationDefinitions 클래스는 IronPDF가 렌더링 과정에서 하이픈 규칙을 가져오는 위치를 정의합니다. Chromium(Chromium) 엔진은 이러한 패턴을 읽고 HTML 요소에 CSS 규칙 hyphens: auto이 있을 때 적용합니다.

CustomHyphenationDefinitions Class란 무엇인가?

이 클래스는 두 가지 속성을 노출합니다:

표 1: CustomHyphenationDefinitions 속성
재산유형필요함설명
PatternSourcestring예하이픈 패턴 파일의 경로 또는 URL (예: hyph-en-us.pat.txt)
ExceptionSourcestring아니요하이픈 예외 파일의 경로 또는 URL (예: hyph-en-us.hyp.txt)

패턴 파일은 GitHub의 tex-hyphen 프로젝트에서 유지 관리하는 TeX 하이픈 형식을 따릅니다. 각 언어는 저장소에 두 개의 파일을 가지고 있습니다: 규칙 패턴을 위한 hyph-{lang}.pat.txt과 예외 목록을 위한 hyph-{lang}.hyp.txt. GitHub에 호스팅된 파일을 참조할 때는 원본 내용 URL(이는 https://raw.githubusercontent.com/로 시작합니다)이 필요합니다 — 표준 GitHub 페이지 URL은 HTML을 반환하며, 패턴 텍스트가 아닙니다.

사용자 정의 하이픈이 내장 언어 설정을 어떻게 우회하나요?

HyphenationLanguage 열거형의 ChromePdfRenderOptions은 미국 영어, 영국 영어, 러시아어에 대한 내장 프리셋을 제공합니다. CustomHyphenation 속성은 둘 다 설정된 경우 이 열거형보다 우선적으로 적용되며 명확한 우선 순위 체인을 따릅니다:

  1. CustomHyphenation — 유효한 PatternSource로 설정되면 사용자 정의 패턴이 사용됩니다
  2. HyphenationLanguage — 사용자 정의 패턴이 구성되지 않은 경우, 내장 언어 프리셋 사용
  3. 없음 — 둘 다 설정되지 않은 경우, 하이픈이 적용되지 않습니다

사용자 정의 패턴 로드에 실패하면 어떻게 되나요?

패턴 로드 중에 발생한 오류는 기록되지만 예외를 발생시키지 않습니다. 렌더링 작업은 실패하기보다는 하이픈 없이 계속 진행됩니다. HyphenationLanguage 값이 구성되어 있는 경우, 렌더러가 내장 프리셋으로 폴백합니다.

이 무음 실패 동작은 프로덕션 환경을 위한 의도적 설계 선택입니다. 원격 패턴 파일을 가져오는 도중의 네트워크 시간 초과, 잘못된 파일 경로, DNS 해상도 실패 또는 잘못된 패턴 내용은 렌더링 파이프라인을 충돌시키지 않습니다. PDF는 여전히 생성되며, 단지 하이픈 된 단어 끊기가 없을 뿐입니다.

트레이드 오프는 가시성입니다. 잘못된 패턴 파일이나 첫 번째 로드에서 도달할 수 없는 URL은 캐싱이 실패 상태도 저장되므로 동일한 소스 값을 사용하는 모든 후속 렌더링에 대해 조용히 영향을 미칩니다. 권고 사항은 패턴 파일을 검증하고 원격 URL에 대한 네트워크 액세스를 애플리케이션 시작 시 또는 CI/CD 배포 확인 중에 확인하는 것입니다 - 렌더링 시점에서가 아니라.

캐싱이 배치 렌더링 성능에 미치는 영향은?

커스텀 하이픈 처리 패턴은 첫 번째 로드 후 패턴 소스 및 예외 소스 값에 의해 키가 메모리에 캐싱됩니다. 같은 소스 경로나 URL을 참조하는 후속 렌더링은 파일을 다시 다운로드하거나 다시 읽지 않고 캐싱된 패턴을 재사용합니다.

대량 PDF 렌더링 워크 플로에 대한 이 행동의 두 가지 실제적인 함의가 있습니다:

성능: 첫 번째 렌더링은 I/O 비용(네트워크 요청 또는 디스크 읽기)을 부담합니다. 그 후의 모든 렌더는 패턴 로딩 관점에서 사실상 무료입니다. 동일한 하이픈 처리 설정으로 수백 개의 PDF를 생성하는 배치 작업의 경우 오버헤드는 무시할 수 있을 정도입니다.

조용한 실패 지속성: 패턴 로드 중 오류가 발생해도 예외가 발생하지 않고 렌더러가 하이픈 처리 없이 계속되므로 잘못된 패턴 파일이나 첫 번째 로드 시 네트워크 실패가 전체 배치에 걸쳐 조용히 지속됩니다. 각 후속 렌더링도 하이픈 처리가 없으며 추가적인 오류 신호는 없습니다. 애플리케이션 시작 또는 배포 시 패턴 파일을 검증하고 URL 접근 가능성을 확인하십시오 - 렌더링 시간에는 하지 마십시오.

캐시 키 식별: 캐시 키는 PatternSource(설정된 경우 ExceptionSource)의 정확한 문자열 값입니다. 같은 URL 또는 파일 경로를 가리키는 두 렌더러 인스턴스는 동일한 캐싱된 패턴을 공유합니다. URL을 변경하면 - 같은 파일의 다른 버전이라도 - 새로 로드하게 됩니다.

프로덕션 배포 전에 파일 콘텐츠를 사전 검증하십시오. 패턴 파일은 유효한 하이픈 처리 텍스트만 포함해야 합니다. 주석, TeX 지시어, 인코딩 선언 또는 비패턴 콘텐츠의 존재는 통합을 실패하게 만듭니다. tex-hyphen 저장소는 수십 개의 언어에 대한 사전 개발된 깨끗한 패턴 파일을 제공합니다.

원격 패턴 소스에 HTTPS를 권장합니다. HTTP도 지원하지만 파일 콘텐츠에 대한 전송 계층 보호를 제공하지 않습니다.

다음 단계는 무엇인가요?

ChromePdfRenderOptions의 CustomHyphenation 속성은 TeX 패턴 파일이 지원하는 모든 언어에 대해 단어 분할 동작을 직접 제어할 수 있게 하며, PdfHyphenationLanguage에서 제공하는 세 가지 내장 프리셋을 넘어서 확장됩니다. 패턴 파일은 원격 URL 또는 로컬 경로에서 로드되며, 첫 사용 후 메모리에 캐싱되고 로드 실패 시 HyphenationLanguage 설정으로 돌아갑니다. 오류는 기록되지만 절대 발생하지 않으므로 패턴 검증은 렌더링 시간 대신 배포 중에 수행해야 합니다.

관련 IronPDF 렌더링 구성에 대해서는 다음을 참조하십시오:

IronPDF의 무료 30일 체험판을 받아 커스텀 하이픈 처리를 라이브 프로젝트에서 테스트하거나, 프로덕션 배포를 위한 라이선스 옵션을 확인하십시오.

아흐마드 소하일
아흐마드 소하일
  지금 바로 엔지니어링 팀과 채팅하세요
풀스택 개발자

아흐마드는 C#, Python 및 웹 기술에 탄탄한 기반을 갖춘 풀스택 개발자입니다. 그는 확장 가능한 소프트웨어 솔루션 구축에 깊은 관심을 가지고 있으며, 실제 응용 프로그램에서 디자인과 기능이 어떻게 조화를 이루는지 탐구하는 것을 즐깁니다.

Iron Software 팀에 합류하기 전, 아흐마드는 자동화 프로젝트와 API 통합 업무를 담당하며 성능 향상과 개발자 경험 개선에 주력했습니다.

그는 여가 시간에 UI/UX 아이디어를 실험하고, 오픈 소스 도구에 기여하며, 복잡한 주제를 더 쉽게 이해할 수 있도록 기술 문서를 작성하는 데 몰두하기도 합니다.

시작할 준비 되셨나요?
Nuget 다운로드 18,135,201 | 버전: 2026.4 방금 출시되었습니다
Still Scrolling Icon

아직도 스크롤하고 계신가요?

빠른 증거를 원하시나요? PM > Install-Package IronPdf
샘플을 실행하세요 HTML이 PDF로 변환되는 것을 지켜보세요.