gpdf.

가이드

폰트

gpdf에서 폰트 및 CJK 텍스트 사용하기

폰트 등록

문서를 생성할 때 TrueType 폰트를 등록합니다:

fontData, _ := os.ReadFile("fonts/NotoSansJP-Regular.ttf")

doc := template.New(
    template.WithPageSize(document.A4),
    template.WithFont("NotoSansJP", fontData),
    template.WithDefaultFont("NotoSansJP", 12),
)

여러 폰트 패밀리

다양한 용도에 맞게 여러 폰트를 등록합니다:

regular, _ := os.ReadFile("fonts/NotoSansJP-Regular.ttf")
bold, _ := os.ReadFile("fonts/NotoSansJP-Bold.ttf")
mono, _ := os.ReadFile("fonts/RobotoMono-Regular.ttf")

doc := template.New(
    template.WithFont("NotoSansJP", regular),
    template.WithFont("NotoSansJP-Bold", bold),
    template.WithFont("RobotoMono", mono),
    template.WithDefaultFont("NotoSansJP", 12),
)

FontFamily()를 사용하여 텍스트 요소에서 폰트를 전환합니다:

c.Text("Regular text")  // uses default NotoSansJP
c.Text("Bold heading", template.FontFamily("NotoSansJP-Bold"), template.FontSize(18))
c.Text("Code snippet", template.FontFamily("RobotoMono"), template.FontSize(10))

CJK 지원

gpdf는 일본어, 중국어, 한국어 텍스트를 최우선으로 지원합니다. CJK 기능에는 금칙처리 규칙(줄 시작/끝에서 특정 문자 금지)에 따른 자동 줄바꿈이 포함됩니다.

fontData, _ := os.ReadFile("fonts/NotoSansJP-Regular.ttf")

doc := template.New(
    template.WithPageSize(document.A4),
    template.WithMargins(document.UniformEdges(document.Mm(20))),
    template.WithFont("NotoSansJP", fontData),
    template.WithDefaultFont("NotoSansJP", 12),
)

page := doc.AddPage()
page.AutoRow(func(r *template.RowBuilder) {
    r.Col(12, func(c *template.ColBuilder) {
        c.Text("日本語テキストのサンプル", template.FontSize(18))
        c.Text("gpdfは純Go・ゼロ依存のPDF生成ライブラリです。")
        c.Text("CJKテキストの改行やレイアウトを正しく処理します。")
    })
})

다국어 CJK 문서

여러 CJK 언어가 포함된 문서에서는 각 폰트를 개별적으로 등록하고 FontFamily()로 전환합니다:

jpFont, _ := os.ReadFile("fonts/NotoSansJP-Regular.ttf")
scFont, _ := os.ReadFile("fonts/NotoSansSC-Regular.ttf")
krFont, _ := os.ReadFile("fonts/NotoSansKR-Regular.ttf")

doc := template.New(
    template.WithPageSize(document.A4),
    template.WithFont("NotoSansJP", jpFont),
    template.WithFont("NotoSansSC", scFont),
    template.WithFont("NotoSansKR", krFont),
    template.WithDefaultFont("NotoSansKR", 12),
)

page := doc.AddPage()
page.AutoRow(func(r *template.RowBuilder) {
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("こんにちは", template.FontFamily("NotoSansJP"))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("你好", template.FontFamily("NotoSansSC"))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("안녕하세요", template.FontFamily("NotoSansKR"))
    })
})

CJK 콘텐츠가 포함된 QR 코드

QR 코드는 일본어를 포함한 유니코드 콘텐츠를 지원합니다:

c.QRCode("こんにちは世界", template.QRSize(document.Mm(30)))

폰트 서브셋팅

gpdf는 자동으로 TrueType 폰트를 서브셋합니다 — 문서에서 실제로 사용된 글리프만 임베딩됩니다. 이는 특히 수만 개의 글리프를 포함할 수 있는 CJK 폰트의 파일 크기를 크게 줄여줍니다.

지원되는 폰트 형식

형식지원
TrueType (.ttf)완전 지원
OpenType (.otf)부분 지원 (TrueType 아웃라인)
WOFF / WOFF2미지원
Type 1미지원

텍스트 셰이핑 제한

gpdf 는 각 문자를 글리프에 일대일로 매핑하며, 텍스트 셰이핑 엔진을 포함하지 않습니다. 문맥에 따른 글리프 치환이나 양방향 텍스트 재정렬이 필요한 문자 체계는 올바르게 배치되지 않습니다.

문자 체계상태
라틴, 키릴, 그리스완전 지원
CJK (일본어, 중국어, 한국어)완전 지원
아랍어, 히브리어, 페르시아어, 우르두어글리프는 정상적으로 임베딩되지만 연결형과 RTL 재정렬은 미지원
데바나가리, 태국어 등 복잡한 문자 체계문맥 셰이핑 미지원

아랍어처럼 연결되는 문자 체계에서는 글자가 연결된 오른쪽에서 왼쪽 배열이 아니라, 고립형 그대로 왼쪽에서 오른쪽으로 그려집니다. 폰트의 GSUB / GPOS 테이블에 정의된 합자와 커닝도 적용되지 않습니다.

텍스트 추출에는 영향이 없습니다. 문자는 ToUnicode CMap 과 함께 임베딩되므로 PDF 에서 복사하거나 pdftotext 를 실행하면 원래 문자열을 얻을 수 있습니다. 스캔한 페이지에 OCR 결과를 겹치는 경우처럼 검색과 선택만 가능하면 되는 용도에서는 이 제한이 결과에 영향을 주지 않습니다.

권장 폰트

폰트용도
Noto Sans JP일본어 텍스트
Noto Sans SC중국어 간체
Noto Sans KR한국어 텍스트
Noto Sans라틴/서양 텍스트
Inter모던 UI 스타일 문서
Roboto Mono코드 및 고정폭 텍스트

JSON 스키마에서 폰트 사용

JSON 스키마를 사용할 때 폰트는 Go 옵션을 통해 등록합니다:

fontData, _ := os.ReadFile("fonts/NotoSansJP-Regular.ttf")

schema := []byte(`{
    "page": {"size": "A4"},
    "body": [
        {"row": {"cols": [
            {"span": 12, "text": "日本語テキスト", "style": {"font": "NotoSansJP"}}
        ]}}
    ]
}`)

doc, err := template.FromJSON(schema, nil,
    template.WithFont("NotoSansJP", fontData),
)

다음 단계