gpdf 패키지

개요

gpdf 패키지는 내부 레이어에서 자주 사용되는 함수를 재수출하는 **퍼사드(Facade)**입니다. 편의를 위해 gpdf를 임포트하거나, 특정 패키지를 직접 임포트할 수 있습니다.

import "github.com/gpdf-dev/gpdf"

// Using facade
doc := gpdf.NewDocument(gpdf.WithPageSize(gpdf.A4))

import (
    "github.com/gpdf-dev/gpdf/template"
    "github.com/gpdf-dev/gpdf/document"
)

// Using packages directly (recommended)
doc := template.New(template.WithPageSize(document.A4))

함수

NewDocument

func NewDocument(opts ...template.Option) *template.Document

새 PDF 문서 빌더를 생성합니다. 이것이 주요 진입점입니다.

doc := gpdf.NewDocument(
    gpdf.WithPageSize(gpdf.A4),
    gpdf.WithMargins(document.UniformEdges(document.Mm(20))),
)

FromJSON

func FromJSON(schema []byte, data any, opts ...template.Option) (*template.Document, error)

JSON 스키마 정의에서 선택적 Go 템플릿 데이터 바인딩을 사용하여 Document를 생성합니다.

doc, err := gpdf.FromJSON(schema, map[string]any{"title": "Report"})

FromTemplate

func FromTemplate(tmpl *template.Template, data any, opts ...template.Option) (*template.Document, error)

JSON 스키마 출력을 생성하는 사전 파싱된 Go 템플릿을 실행하여 Document를 생성합니다.

TemplateFuncMap

func TemplateFuncMap() template.FuncMap

Go 템플릿을 파싱할 때 사용할 헬퍼 함수(toJSON 등)를 반환합니다.

문서 옵션

함수	설명
`WithPageSize(size)`	페이지 치수 설정 (`A4`, `A3`, `Letter`, `Legal`)
`WithMargins(edges)`	페이지 여백 설정
`WithFont(family, data)`	TrueType 폰트 등록 (`[]byte` 허용)
`WithDefaultFont(family, size)`	기본 폰트 패밀리 및 크기 설정
`WithMetadata(meta)`	문서 메타데이터 설정
`WithEncryption(opts...)`	AES-256 암호화 활성화
`WithPDFA(opts...)`	PDF/A 준수 활성화

문서 메타데이터

gpdf.WithMetadata(document.DocumentMetadata{
    Title:   "Invoice #INV-2026-001",
    Author:  "ACME Corporation",
    Subject: "Monthly Invoice",
    Creator: "gpdf v1.0.4",
})

페이지 크기

상수	치수
`gpdf.A4` / `document.A4`	210mm x 297mm (595.28pt x 841.89pt)
`gpdf.A3` / `document.A3`	297mm x 420mm (841.89pt x 1190.55pt)
`gpdf.Letter` / `document.Letter`	8.5" x 11" (612pt x 792pt)
`gpdf.Legal` / `document.Legal`	8.5" x 14" (612pt x 1008pt)

Document 메서드

AddPage

func (d *Document) AddPage() *PageBuilder

새 페이지를 추가하고 해당 빌더를 반환합니다.

Header / Footer

func (d *Document) Header(fn func(p *PageBuilder))
func (d *Document) Footer(fn func(p *PageBuilder))

모든 페이지에 반복되는 콘텐츠를 정의합니다.

Generate / Render

func (d *Document) Generate() ([]byte, error)
func (d *Document) Render(w io.Writer) error

Generate()는 PDF를 바이트 슬라이스로 반환합니다. Render()는 io.Writer에 직접 씁니다.

PageBuilder 메서드

Row

func (p *PageBuilder) Row(height document.Value, fn func(r *RowBuilder))
func (p *PageBuilder) AutoRow(fn func(r *RowBuilder))

Row()는 고정 높이 행을 생성합니다. AutoRow()는 콘텐츠에 맞게 조절되는 행을 생성합니다.

RowBuilder 메서드

Col

func (r *RowBuilder) Col(span int, fn func(c *ColBuilder))

12열 그리드에서 span열을 차지하는 열을 생성합니다.

ColBuilder 메서드

메서드	설명
`Text(text, opts...)`	스타일 옵션과 함께 텍스트 추가
`Image(data, opts...)`	이미지 추가 (JPEG 또는 PNG 바이트)
`Table(headers, rows, opts...)`	테이블 추가
`List(items, opts...)`	비순서 목록 추가
`OrderedList(items, opts...)`	순서 목록 추가
`Line(opts...)`	수평선 추가
`Spacer(height)`	수직 간격 추가
`QRCode(data, opts...)`	QR 코드 추가
`Barcode(data, opts...)`	바코드 추가 (Code 128)
`RichText(fn)`	혼합 스타일 인라인 텍스트 추가
`PageNumber(opts...)`	현재 페이지 번호
`TotalPages(opts...)`	전체 페이지 수

QR 코드 옵션

함수	설명
`QRSize(value)`	표시 크기 (너비 = 높이)
`QRErrorCorrection(level)`	오류 정정: `LevelL`, `LevelM`, `LevelQ`, `LevelH`
`QRScale(s)`	QR 모듈당 픽셀 수

바코드 옵션

함수	설명
`BarcodeWidth(value)`	표시 너비
`BarcodeHeight(value)`	표시 높이
`BarcodeFormat(format)`	바코드 형식 (기본값: Code 128)

기존 PDF 작업

Open

func Open(data []byte, opts ...template.Option) (*template.ExistingDocument, error)

기존 PDF를 읽기 및 수정을 위해 엽니다. 증분 업데이트(비파괴적 추가)를 통한 오버레이 작업을 지원하는 ExistingDocument를 반환합니다.

doc, err := gpdf.Open(pdfBytes)

ExistingDocument 메서드

메서드	설명
`PageCount() (int, error)`	PDF의 페이지 수 반환
`Overlay(pageIndex int, fn func(p *PageBuilder)) error`	특정 페이지 위에 콘텐츠 추가 (0부터 시작하는 인덱스)
`EachPage(fn func(pageIndex int, p *PageBuilder)) error`	모든 페이지 위에 콘텐츠 추가
`FlattenForms() error`	모든 AcroForm 필드를 정적 페이지 콘텐츠로 플래트닝 Since v1.0.4
`Save() ([]byte, error)`	수정된 PDF를 바이트 슬라이스로 반환

doc, err := gpdf.Open(pdfBytes, gpdf.WithFont("NotoSans", fontData))

// Add watermark on page 1
doc.Overlay(0, func(p *template.PageBuilder) {
    p.Absolute(document.Mm(40), document.Mm(120), func(c *template.ColBuilder) {
        c.Text("DRAFT", template.FontSize(72),
            template.TextColor(pdf.Gray(0.85)))
    })
})

// Add page numbers on every page
count, _ := doc.PageCount()
doc.EachPage(func(i int, p *template.PageBuilder) {
    p.Absolute(document.Mm(170), document.Mm(285), func(c *template.ColBuilder) {
        c.Text(fmt.Sprintf("%d / %d", i+1, count),
            template.FontSize(10), template.AlignRight())
    }, template.AbsoluteWidth(document.Mm(20)))
})

result, err := doc.Save()

PDF 병합 Since v1.0.2

Merge

func Merge(sources []Source, opts ...MergeOption) ([]byte, error)

여러 PDF 소스의 페이지를 하나의 출력 PDF로 결합합니다.

Source

type Source struct {
    Data  []byte    // 원시 PDF 바이트
    Pages PageRange // 포함할 페이지. 제로값 = 모든 페이지
}

PageRange

type PageRange struct {
    From int  // 1 기반 시작 페이지. 0 = 첫 번째 페이지
    To   int  // 1 기반 끝 페이지. 0 = 마지막 페이지
}

병합 옵션

함수	설명
`WithMergeMetadata(title, author, producer)`	병합 출력에 문서 정보(제목, 저자, 제작자) 설정

컴포넌트 생성자

함수	설명
`NewInvoice(data)`	청구서 PDF 생성
`NewReport(data)`	보고서 PDF 생성
`NewLetter(data)`	비즈니스 레터 PDF 생성

자세한 사용법은 컴포넌트를 참조하세요.