요소

텍스트

가장 기본적인 요소입니다. 선택적 스타일링과 함께 텍스트를 추가합니다:

c.Text("Hello, World!")
c.Text("Styled text", template.FontSize(18), template.Bold())
c.Text("Red centered", template.TextColor(pdf.Red), template.AlignCenter())

텍스트 옵션

옵션	설명
`FontSize(size)`	폰트 크기 (포인트 단위, 기본값: 12)
`Bold()`	굵게
`Italic()`	기울임꼴
`FontFamily(name)`	등록된 폰트 사용
`TextColor(color)`	전경 색상
`BgColor(color)`	배경 색상
`AlignLeft()`	왼쪽 정렬 (기본값)
`AlignCenter()`	가운데 정렬
`AlignRight()`	오른쪽 정렬
`Underline()`	밑줄 장식
`Strikethrough()`	취소선 장식
`LetterSpacing(pts)`	문자 간 추가 간격
`TextIndent(value)`	첫 줄 들여쓰기

리치 텍스트

RichText()를 사용한 혼합 스타일 인라인 텍스트:

c.RichText(func(rt *template.RichTextBuilder) {
    rt.Span("Normal text ")
    rt.Span("bold", template.Bold())
    rt.Span(" and ")
    rt.Span("red", template.TextColor(pdf.Red))
    rt.Span(" in one line.")
})

┌─────────────────────────────────────────────┐
│  Normal text bold and red in one line.      │
│              ^^^^     ^^^                   │
│              bold     red color             │
└─────────────────────────────────────────────┘

테이블

헤더와 데이터 행이 있는 테이블:

// Basic table
c.Table(
    []string{"Name", "Age", "City"},
    [][]string{
        {"Alice", "30", "Tokyo"},
        {"Bob", "25", "New York"},
        {"Charlie", "35", "London"},
    },
)

┌──────────┬──────┬──────────┐
│  Name    │ Age  │  City    │ ← 헤더 (굵게)
├──────────┼──────┼──────────┤
│  Alice   │  30  │  Tokyo   │
│  Bob     │  25  │  New York│
│  Charlie │  35  │  London  │
└──────────┴──────┴──────────┘

스타일이 적용된 테이블

darkBlue := pdf.RGBHex(0x1A237E)
lightGray := pdf.RGBHex(0xF5F5F5)

c.Table(
    []string{"Product", "Category", "Qty", "Unit Price", "Total"},
    [][]string{
        {"Laptop Pro 15", "Electronics", "2", "$1,299.00", "$2,598.00"},
        {"Wireless Mouse", "Accessories", "10", "$29.99", "$299.90"},
        {"USB-C Hub", "Accessories", "5", "$49.99", "$249.95"},
        {"Monitor 27\"", "Electronics", "3", "$399.00", "$1,197.00"},
        {"Keyboard", "Accessories", "10", "$79.99", "$799.90"},
        {"Webcam HD", "Electronics", "4", "$89.99", "$359.96"},
    },
    template.ColumnWidths(30, 20, 10, 20, 20),
    template.TableHeaderStyle(
        template.TextColor(pdf.White),
        template.BgColor(darkBlue),
    ),
    template.TableStripe(lightGray),
)

┌─────────────┬────────────┬─────┬───────────┬──────────┐
│  Product    │  Category  │ Qty │Unit Price │  Total   │ ← 흰색 글자 + 진한 파란색 배경
├─────────────┼────────────┼─────┼───────────┼──────────┤
│  Laptop Pro │ Electronics│  2  │ $1,299.00 │$2,598.00 │ ← 흰색 배경
│  Wireless.. │ Accessories│ 10  │    $29.99 │  $299.90 │ ← 회색 스트라이프
│  USB-C Hub  │ Accessories│  5  │    $49.99 │  $249.95 │ ← 흰색 배경
│  Monitor 27"│ Electronics│  3  │   $399.00 │$1,197.00 │ ← 회색 스트라이프
│  Keyboard   │ Accessories│ 10  │    $79.99 │  $799.90 │ ← 흰색 배경
│  Webcam HD  │ Electronics│  4  │    $89.99 │  $359.96 │ ← 회색 스트라이프
└─────────────┴────────────┴─────┴───────────┴──────────┘

테이블 옵션

옵션	설명
`ColumnWidths(widths...)`	열 너비 백분율 (합계가 100이어야 함)
`ColumnAlign(aligns...)`	Since v1.0.10 열별 수평 정렬: `AlignLeft`, `AlignCenter`, `AlignRight` (헤더와 본문 모두에 적용)
`TableHeaderStyle(opts...)`	헤더 행 스타일
`TableStripe(color)`	교대 행 배경 색상
`TableCellVAlign(align)`	수직 정렬: `VAlignTop`, `VAlignMiddle`, `VAlignBottom`
`WithTableBorder(spec)`	테이블 외곽 테두리
`WithTableCellBorder(spec)`	헤더 + 본문의 모든 셀에 동일한 테두리 (Excel 스타일 그리드)
`WithTableBorderCollapse(b)`	인접한 셀 테두리를 병합
`WithTableBackground(color)`	테이블 외곽 박스 배경 채우기

테두리와 배경

Since v1.0.7

외곽 프레임, 셀별 그리드 라인 또는 배경 채우기를 추가할 수 있습니다. template.Border(...) 로 BorderSpec 을 만들고 WithTableBorder (외곽) 또는 WithTableCellBorder (모든 셀) 로 적용합니다:

outer := template.Border(
    template.BorderWidth(document.Pt(1)),
    template.BorderColor(pdf.RGBHex(0x1A237E)),
)
grid := template.Border(
    template.BorderWidth(document.Pt(0.5)),
    template.BorderColor(pdf.Gray(0.5)),
)

// 외곽 프레임만
c.Table(header, rows, template.WithTableBorder(outer))

// 모든 셀에 Excel 스타일 그리드
c.Table(header, rows, template.WithTableCellBorder(grid))

// 외곽 + 그리드 + 배경
c.Table(header, rows,
    template.WithTableBorder(outer),
    template.WithTableCellBorder(grid),
    template.WithTableBackground(pdf.RGBHex(0xFAFAFA)),
)

// 점선 그리드
dashed := template.Border(
    template.BorderWidth(document.Pt(0.75)),
    template.BorderColor(pdf.RGBHex(0x0D47A1)),
    template.BorderLine(document.BorderDashed),
)
c.Table(header, rows, template.WithTableCellBorder(dashed))

전체 BorderSpec 빌더 레퍼런스는 테두리 를 참조하세요.

테이블 수직 정렬

c.Table(
    []string{"Align", "Short", "Long Content"},
    [][]string{
        {"Top", "A", "This is a longer text that wraps to multiple lines"},
        {"Middle", "B", "Another longer text for demonstration purposes"},
    },
    template.TableCellVAlign(document.VAlignMiddle),
)

테이블 열 정렬

Since v1.0.10

열별로 수평 정렬을 지정할 수 있습니다. 일반적인 사용 사례는 숫자나 통화 열을 우측 정렬하는 것입니다. 각 인수는 동일 인덱스의 열에 적용되며, 헤더와 본문 양쪽에 반영됩니다. 지정되지 않은 열은 기본 좌측 정렬로 폴백됩니다.

c.Table(
    []string{"상품", "수량", "가격"},
    [][]string{
        {"사과",   "3",   "₩1,500"},
        {"바나나", "12",  "₩300"},
        {"체리",   "120", "₩5,000"},
    },
    template.ColumnAlign(
        document.AlignLeft,   // 상품
        document.AlignRight,  // 수량
        document.AlignRight,  // 가격
    ),
)

이미지

JPEG 또는 PNG 이미지를 추가합니다:

imgData, _ := os.ReadFile("photo.jpg")

c.Image(imgData)
c.Image(imgData, template.FitWidth(document.Mm(80)))
c.Image(imgData, template.FitHeight(document.Mm(50)))

이미지 옵션

옵션	설명
`FitWidth(value)`	지정된 너비로 축소
`FitHeight(value)`	지정된 높이로 축소
`WithFitMode(mode)`	맞춤 모드: `FitContain`, `FitCover`, `FitStretch`, `FitOriginal`
`WithAlign(align)`	수평 정렬: `AlignLeft`, `AlignCenter`, `AlignRight`
`MinDisplayWidth(v)`	이 너비 미만으로 축소되면 다음 페이지로 오버플로우
`MinDisplayHeight(v)`	이 높이 미만으로 축소되면 다음 페이지로 오버플로우
`WithImageBorder(spec)`	이미지 주변에 테두리
`WithImageBackground(color)`	이미지 박스 배경 채우기 (투명 PNG 에 유용)

이미지 맞춤 모드

// Contain: scale to fit, preserve aspect ratio (default)
c.Image(data, template.WithFitMode(document.FitContain))

// Cover: scale to fill, may crop
c.Image(data, template.WithFitMode(document.FitCover))

// Stretch: fill bounds, may distort
c.Image(data, template.WithFitMode(document.FitStretch))

// Original: use original dimensions
c.Image(data, template.WithFitMode(document.FitOriginal))

이미지 정렬

c.Image(data, template.FitWidth(document.Mm(40)), template.WithAlign(document.AlignCenter))
c.Image(data, template.FitWidth(document.Mm(40)), template.WithAlign(document.AlignRight))

테두리와 배경

Since v1.0.7

이미지에 테두리를 두르고 박스를 채울 수 있습니다 (투명 PNG 에 유용):

c.Image(pngData,
    template.FitWidth(document.Mm(60)),
    template.WithImageBorder(template.Border(
        template.BorderWidth(document.Pt(2)),
        template.BorderColor(pdf.RGBHex(0xE53935)),
    )),
    template.WithImageBackground(pdf.RGBHex(0xFFF8E1)),
)

전체 BorderSpec 빌더 레퍼런스는 테두리 를 참조하세요.

박스

Since v1.0.7

임의의 컬럼 내용을 테두리, 배경, 패딩이 있는 사각형 컨테이너로 감쌉니다. 콜아웃, 알림 박스, 관련 요소의 그룹화에 유용합니다:

c.Box(func(c *template.ColBuilder) {
    c.Text("박스 안", template.Bold())
    c.Text("본문 두 줄 예시.")
},
    template.WithBoxBorder(template.Border(
        template.BorderWidth(document.Pt(1)),
        template.BorderColor(pdf.RGBHex(0x1A237E)),
    )),
    template.WithBoxBackground(pdf.RGBHex(0xE8EAF6)),
    template.WithBoxPadding(document.UniformEdges(document.Mm(4))),
)

박스 옵션

옵션	설명
`WithBoxBorder(spec)`	박스 주변 테두리
`WithBoxBackground(color)`	배경색
`WithBoxPadding(edges)`	내부 여백
`WithBoxMargin(edges)`	외부 여백
`WithBoxWidth(value)`	명시적 너비
`WithBoxHeight(value)`	명시적 높이

테두리

Since v1.0.7

template.Border(...) 는 재사용 가능한 BorderSpec 을 만듭니다. 테이블 (WithTableBorder / WithTableCellBorder), 이미지 (WithImageBorder), 박스 (WithBoxBorder), 텍스트 (WithTextBorder) 에 적용할 수 있습니다:

spec := template.Border(
    template.BorderWidth(document.Pt(1)),       // 4 면 균일
    template.BorderColor(pdf.RGBHex(0x1A237E)),
    template.BorderLine(document.BorderSolid),  // BorderSolid | BorderDashed | BorderDotted
)

너비를 지정하지 않은 경우 기본값은 1pt 검정 실선 입니다.

테두리 헬퍼

옵션	설명
`Border(opts...)`	`BorderSpec` 을 빌드
`BorderWidth(v)`	4 면 균일한 너비
`BorderWidths(t, r, b, l)`	CSS 순서 (top, right, bottom, left) 의 면별 너비
`BorderColor(c)`	테두리 색
`BorderLine(style)`	선 스타일: `BorderSolid`, `BorderDashed`, `BorderDotted`, `BorderNone`

비순서 목록

c.List([]string{
    "Declarative document definition",
    "All element types supported",
    "Style options (bold, italic, color, align)",
    "Header and footer support",
})

┌─────────────────────────────────────────────┐
│  • Declarative document definition          │
│  • All element types supported              │
│  • Style options (bold, italic, color, ...)  │
│  • Header and footer support                │
└─────────────────────────────────────────────┘

순서 목록

c.OrderedList([]string{
    "Text with styles",
    "Tables with headers",
    "Lists (ordered/unordered)",
    "Lines and spacers",
    "QR codes and barcodes",
})

┌─────────────────────────────────────────────┐
│  1. Text with styles                        │
│  2. Tables with headers                     │
│  3. Lists (ordered/unordered)               │
│  4. Lines and spacers                       │
│  5. QR codes and barcodes                   │
└─────────────────────────────────────────────┘

목록 옵션

옵션	설명
`ListIndent(value)`	왼쪽 들여쓰기

선

선택적 색상 및 두께가 있는 수평선:

// Default line (gray, 1pt)
c.Line()

// Colored line
c.Line(template.LineColor(pdf.Red))
c.Line(template.LineColor(pdf.Blue))

// Custom thickness
c.Line(template.LineThickness(document.Pt(0.5)))   // thin
c.Line(template.LineThickness(document.Pt(2)))     // medium
c.Line(template.LineThickness(document.Pt(5)))     // thick

// Color + thickness
c.Line(
    template.LineColor(pdf.RGBHex(0x1A237E)),
    template.LineThickness(document.Pt(2)),
)

┌─────────────────────────────────────────────┐
│  Default line:                              │
│  ─────────────────────────────── (gray 1pt) │
│  Red line:                                  │
│  ─────────────────────────────── (red)      │
│  Thin (0.5pt):                              │
│  ─────────────────────────────── (thin)     │
│  Thick (5pt):                               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ (thick)    │
└─────────────────────────────────────────────┘

선 옵션

옵션	설명
`LineColor(color)`	선 색상
`LineThickness(value)`	선 두께

스페이서

요소 간 수직 간격을 추가합니다:

c.Text("Before spacer")
c.Spacer(document.Mm(10))    // 10mm gap
c.Text("After spacer")

c.Spacer(document.Mm(5))     // 5mm
c.Spacer(document.Mm(15))    // 15mm
c.Spacer(document.Mm(30))    // 30mm

┌─────────────────────────────────────────────┐
│  Before spacer                              │
│                                             │
│                  ↕ 10mm                     │
│                                             │
│  After spacer                               │
└─────────────────────────────────────────────┘

QR 코드

텍스트 또는 URL에서 QR 코드를 생성합니다:

// Basic QR code
c.QRCode("https://gpdf.dev")

// With custom size
c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(30)))

// With error correction level
c.QRCode("HELLO", template.QRSize(document.Mm(25)),
    template.QRErrorCorrection(qrcode.LevelH))

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

다양한 크기의 QR 코드

page.AutoRow(func(r *template.RowBuilder) {
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("20mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(20)))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("30mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(30)))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("40mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(40)))
    })
})

┌───────────────┬───────────────┬───────────────┐
│  20mm         │  30mm         │  40mm         │
│  ┌──┐         │  ┌────┐       │  ┌──────┐     │
│  │QR│         │  │ QR │       │  │  QR  │     │
│  └──┘         │  └────┘       │  │      │     │
│               │               │  └──────┘     │
└───────────────┴───────────────┴───────────────┘

오류 정정 레벨

레벨	복구율	적합한 용도
`qrcode.LevelL`	~7%	깨끗한 환경
`qrcode.LevelM`	~15%	일반 용도 (기본값)
`qrcode.LevelQ`	~25%	산업 용도
`qrcode.LevelH`	~30%	열악한 환경

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

c.QRCode("HELLO", template.QRErrorCorrection(qrcode.LevelH))

QR 코드 옵션

옵션	설명
`QRSize(value)`	표시 크기 (너비 = 높이)
`QRMinSize(value)`	최소 표시 크기 — 이 값 미만이 되면 다음 페이지로 이동
`QRErrorCorrection(level)`	오류 정정 레벨
`QRScale(s)`	QR 모듈당 픽셀 수

최소 크기

Since v1.0.6

QRMinSize는 레이아웃이 QR 코드를 설정된 최소 크기 미만으로 축소하는 것을 방지합니다. 현재 페이지의 남은 공간이 해당 최소 크기보다 작아지면, 스캔할 수 없는 크기로 렌더링하는 대신 다음 페이지로 이동합니다.

c.QRCode("https://gpdf.dev",
    template.QRSize(document.Mm(30)),
    template.QRMinSize(document.Mm(20)))

바코드

Code 128 바코드를 생성합니다:

// Basic barcode
c.Barcode("INV-2026-0001")

// With custom width
c.Barcode("PRODUCT-A-12345", template.BarcodeWidth(document.Mm(80)))

// With custom height
c.Barcode("SMALL-BAR", template.BarcodeHeight(document.Mm(10)))

// Numeric data (automatically optimized with Code C)
c.Barcode("1234567890")

열 내 바코드

page.AutoRow(func(r *template.RowBuilder) {
    r.Col(6, func(c *template.ColBuilder) {
        c.Text("Item A", template.FontSize(9))
        c.Barcode("ITEM-A-001", template.BarcodeWidth(document.Mm(60)))
    })
    r.Col(6, func(c *template.ColBuilder) {
        c.Text("Item B", template.FontSize(9))
        c.Barcode("ITEM-B-002", template.BarcodeWidth(document.Mm(60)))
    })
})

┌────────────────────────┬────────────────────────┐
│  Item A                │  Item B                │
│  ║║│║║│║║║│║║│║║│      │  ║║│║║│║║║│║║│║║│      │
│  ITEM-A-001            │  ITEM-B-002            │
└────────────────────────┴────────────────────────┘

바코드 옵션

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

절대 위치 지정

일반적인 그리드 흐름 외부에서 페이지의 정확한 XY 좌표에 요소를 배치합니다. 워터마크, 스탬프, 로고, 오버레이에 유용합니다.

page.Absolute(document.Mm(120), document.Mm(20), func(c *template.ColBuilder) {
    c.Text("CONFIDENTIAL", template.FontSize(20), template.Bold(), template.TextColor(pdf.Red))
})

// With explicit size
page.Absolute(document.Mm(10), document.Mm(250), func(c *template.ColBuilder) {
    c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(20)))
}, gpdf.AbsoluteWidth(document.Mm(25)), gpdf.AbsoluteHeight(document.Mm(25)))

// Use page corner as origin (ignores margins)
page.Absolute(document.Mm(0), document.Mm(0), func(c *template.ColBuilder) {
    c.Text("Top-left corner of page")
}, gpdf.AbsoluteOriginPage())

┌─ Page ──────────────────────────────────────────┐
│  ┌─ Content Area ───────────────────────────┐   │
│  │                                          │   │
│  │   [Normal flow content]                  │   │
│  │                                          │   │
│  │              ┌──────────────┐            │   │
│  │              │ CONFIDENTIAL │ ← absolute │   │
│  │              └──────────────┘   (120,20) │   │
│  │                                          │   │
│  │   ┌──┐                                   │   │
│  │   │QR│ ← absolute (10,250)               │   │
│  │   └──┘                                   │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

좌표 원점

원점	설명	기본값
콘텐츠 영역	콘텐츠 영역의 좌상단 기준 XY (여백 내부)	예
페이지	페이지 좌상단 모서리 기준 XY (여백 무시)	아니오

절대 위치 지정 옵션

옵션	설명
`AbsoluteWidth(value)`	절대 블록의 명시적 너비
`AbsoluteHeight(value)`	절대 블록의 명시적 높이
`AbsoluteOriginPage()`	콘텐츠 영역 대신 페이지 모서리를 원점으로 사용

페이지 번호 / 전체 페이지 수

머리글이나 바닥글에서 자동 페이지 번호 매기기:

// Current page number (e.g., "1", "2", "3")
c.PageNumber(template.AlignRight(), template.FontSize(8))

// Total page count (e.g., "4 total pages")
c.TotalPages(template.AlignRight(), template.FontSize(9))

둘 다 스타일링을 위한 표준 텍스트 옵션을 지원합니다.