DocumentBuilder 플루언트 API

DocumentBuilder는 텍스트 배치, 폰트, 주석, 폼 필드, 콘텐츠 요소를 완전히 제어하면서 페이지별로 PDF 문서를 구성하는 플루언트 API입니다.

바인딩 커버리지 (v0.3.38). DocumentBuilder + FluentPageBuilder + EmbeddedFont는 Rust, Python, Node/TypeScript, C#, Go, WASM에서 모두 제공됩니다. 모든 바인딩이 동일한 기능을 노출합니다. 다중 페이지 구성, 임베디드 폰트를 통한 CJK / 키릴 / 그리스 문자, 15개 주석 메서드, 5개 AcroForm 위젯 타입, 그래픽 프리미티브 (rect, filled_rect, line), AES-256 암호화, HTML+CSS 파이프라인 등.

빠른 예제

Rust

use pdf_oxide::writer::{DocumentBuilder, PageSize, DocumentMetadata};

let mut builder = DocumentBuilder::new()
    .metadata(DocumentMetadata::new().title("My Document"));

builder
    .page(PageSize::Letter)
        .at(72.0, 720.0)
        .heading(1, "Hello, World!")
        .paragraph("This is a PDF document created with DocumentBuilder.")
        .done();

let bytes = builder.build()?;
std::fs::write("output.pdf", bytes)?;

Python

from pdf_oxide import DocumentBuilder, EmbeddedFont

font = EmbeddedFont.from_file("DejaVuSans.ttf")
pdf = (DocumentBuilder()
    .register_embedded_font("DejaVu", font)
    .a4_page()
        .font("DejaVu", 12).at(72, 720).text("Hello, World!")
        .highlight((1.0, 1.0, 0.0))
    .done()
    .build())
open("output.pdf", "wb").write(pdf)

Node / TypeScript

import { DocumentBuilder, EmbeddedFont } from "pdf-oxide";

const font = await EmbeddedFont.fromFile("DejaVuSans.ttf");
const bytes = new DocumentBuilder()
  .registerEmbeddedFont("DejaVu", font)
  .a4Page()
    .font("DejaVu", 12).at(72, 720).text("Hello, World!")
    .highlight([1.0, 1.0, 0.0])
  .done()
  .build();

C#

using PdfOxide;

using var font = EmbeddedFont.FromFile("DejaVuSans.ttf");
var bytes = DocumentBuilder.Create()
    .RegisterEmbeddedFont("DejaVu", font)
    .A4Page()
        .Font("DejaVu", 12).At(72, 720).Text("Hello, World!")
        .Highlight(1.0, 1.0, 0.0)
    .Done()
    .Build();
File.WriteAllBytes("output.pdf", bytes);

Go (CGo 경로, CGO_ENABLED=1 필요)

import pdfoxide "github.com/yfedoseev/pdf_oxide/go"

font, _ := pdfoxide.EmbeddedFontFromFile("DejaVuSans.ttf")
defer font.Close()

builder := pdfoxide.NewDocumentBuilder()
builder.RegisterEmbeddedFont("DejaVu", font)
builder.A4Page().
    Font("DejaVu", 12).At(72, 720).Text("Hello, World!").
    Highlight(1.0, 1.0, 0.0).
    Done()
bytes, _ := builder.Build()

WASM (브라우저 / Node / 번들러 — API 동일)

import init, { DocumentBuilder, EmbeddedFont } from "pdf-oxide-wasm/web";
await init();

const font = await fetch("/DejaVuSans.ttf").then(r => r.arrayBuffer());
const bytes = new DocumentBuilder()
  .registerEmbeddedFont("DejaVu", EmbeddedFont.fromBytes(new Uint8Array(font), "DejaVu"))
  .a4Page()
    .font("DejaVu", 12).at(72, 720).text("Hello, World!")
  .done()
  .build();

전체 API 레퍼런스

DocumentBuilder

DocumentBuilder::new() — 빌더 생성

let mut builder = DocumentBuilder::new();

.metadata(metadata) — 문서 메타데이터 설정

use pdf_oxide::writer::DocumentMetadata;

let mut builder = DocumentBuilder::new()
    .metadata(
        DocumentMetadata::new()
            .title("Report")
            .author("Jane Smith")
            .subject("Q4 Analysis")
            .keywords("finance, quarterly")
            .creator("MyApp")
    );

.page(size) — 페이지 추가

페이지에 콘텐츠를 추가하기 위한 FluentPageBuilder를 반환합니다. 작업이 끝나면 .done()을 호출하세요.

use pdf_oxide::writer::PageSize;

builder.page(PageSize::A4)
    .at(72.0, 770.0)
    .text("Hello")
    .done();

.letter_page() / .a4_page() — 페이지 편의 메서드

builder.letter_page().text("US Letter page").done();
builder.a4_page().text("A4 page").done();

.build() — PDF 바이트 생성

let bytes: Vec<u8> = builder.build()?;

.save(path) — 빌드하고 파일로 저장

builder.save("output.pdf")?;

.save_encrypted(path, user_pw, owner_pw) — AES-256 암호화

v0.3.38에서 추가되었습니다. 모든 바인딩에서 제공됩니다.

DocumentBuilder::new()
    .a4_page().text("secret").done()
    .save_encrypted("out.pdf", "user-pw", "owner-pw")?;

(DocumentBuilder()
    .a4_page().text("secret").done()
    .save_encrypted("out.pdf", "user-pw", "owner-pw"))

DocumentBuilder.Create()
    .A4Page().Text("secret").Done()
    .SaveEncrypted("out.pdf", "user-pw", "owner-pw");

메모리 출력이 필요할 때는 .to_bytes_encrypted(user_pw, owner_pw)도 사용할 수 있고, 알고리즘과 권한을 세밀하게 지정하려면 Rust에서 .save_with_encryption(path, algorithm, permissions, user_pw, owner_pw)를 사용할 수 있습니다.

DocumentMetadata

문서 수준 메타데이터 빌더.

메서드	설명
.title(s)	문서 제목 설정
.author(s)	문서 저자 설정
.subject(s)	문서 주제 설정
.keywords(s)	문서 키워드 설정
.creator(s)	생성 애플리케이션 설정

FluentPageBuilder

builder.page(size)에서 반환됩니다. 모든 메서드는 체이닝을 위해 self를 반환합니다 (.done() 제외).

텍스트와 위치 지정

메서드	설명
.at(x, y)	커서 위치 설정 (좌측 하단 기준 포인트)
.text(s)	현재 커서 위치에 텍스트 추가
.heading(level, s)	제목 추가 (1–6, 적절한 폰트)
.paragraph(s)	자동 워드랩이 적용된 단락 추가
.font(name, size)	이후 텍스트에 적용할 폰트 설정
.text_config(config)	전체 텍스트 설정 지정
.space(points)	수직 공백 추가
.horizontal_rule()	수평 구분선 추가
.element(elem)	ContentElement 원본 추가
.elements(vec)	여러 콘텐츠 요소 한 번에 추가

주석

메서드	설명
.link_url(url)	마지막 텍스트에 URL 링크 연결
.link_page(page_index)	마지막 텍스트를 내부 페이지로 링크
.link_named(destination)	명명된 대상으로 링크
.highlight(color)	마지막 텍스트 하이라이트 (RGB 튜플)
.underline(color)	마지막 텍스트 밑줄
.strikeout(color)	마지막 텍스트 취소선
.squiggly(color)	마지막 텍스트에 물결 밑줄
.sticky_note(text)	커서 위치에 스티키 노트 추가
.sticky_note_with_icon(text, icon)	특정 아이콘으로 스티키 노트 추가
.sticky_note_at(x, y, text)	특정 위치에 스티키 노트 추가
.stamp(stamp_type)	커서 위치에 스탬프 추가
.stamp_at(rect, stamp_type)	지정한 사각형에 스탬프 추가
.freetext(rect, text)	자유 텍스트 주석 추가
.freetext_styled(rect, text, font, size)	스타일 적용 자유 텍스트 주석 추가
.watermark(text)	페이지 전체에 대각선 워터마크 추가
.watermark_confidential()	“CONFIDENTIAL” 프리셋 워터마크
.watermark_draft()	“DRAFT” 프리셋 워터마크
.watermark_custom(watermark)	사용자 지정 워터마크 주석
.add_annotation(annotation)	모든 주석 유형 추가

AcroForm 위젯

v0.3.38부터 모든 바인딩에서 추가되었습니다. 모든 위치는 페이지의 좌측 하단 원점 기준 PDF 포인트 단위입니다.

메서드	설명
.text_field(name, x, y, w, h, default_value=None)	단일 줄 텍스트 입력
.checkbox(name, x, y, w, h, checked)	체크박스 위젯
.combo_box(name, x, y, w, h, options, selected=None)	드롭다운 선택
.radio_group(name, buttons, selected=None)	라디오 그룹. buttons는 (export_value, x, y, w, h)의 리스트
.push_button(name, x, y, w, h, caption)	라벨이 붙은 클릭 가능한 버튼

(DocumentBuilder()
    .a4_page()
        .text_field("name", 150, 680, 200, 20, "Jane Doe")
        .checkbox("subscribe", 72, 650, 15, 15, True)
        .combo_box("country", 150, 620, 200, 20, ["US", "UK", "DE"], "US")
        .radio_group("tier", [("free", 72, 590, 15, 15), ("pro", 120, 590, 15, 15)], "pro")
        .push_button("submit", 72, 540, 80, 25, "Submit")
    .done()
    .save("form.pdf"))

그래픽 프리미티브

v0.3.38부터 모든 바인딩에 추가되었습니다: rect(x, y, w, h) (테두리만), filled_rect(x, y, w, h, color) (RGB 튜플로 채움), line(x1, y1, x2, y2). 모두 동일한 FluentPageBuilder 체인에서 호출하며, 폼 배경, 구분선, 간단한 테이블 테두리에 충분합니다.

경로 / 패턴 / 그라데이션 / ExtGState를 완전히 제어하고 싶다면 ContentStreamBuilder를 사용하세요 (Rust 전용 — 그래픽, 패턴 및 셰이딩 참고).

.done() — 페이지 마무리

제어를 DocumentBuilder로 되돌립니다.

builder.page(PageSize::Letter)
    .at(72.0, 720.0)
    .text("Content")
    .done();  // 빌더로 복귀

TextConfig

텍스트 렌더링 설정입니다.

use pdf_oxide::writer::TextConfig;

let config = TextConfig {
    font: "Times-Roman".to_string(),
    size: 14.0,
    align: TextAlign::Center,
    line_height: 1.5,
};

필드	타입	기본값
font	String	"Helvetica"
size	f32	12.0
align	TextAlign	Left
line_height	f32	1.2

PageSize

Variant	너비 × 높이 (포인트)
Letter	612 × 792
A4	595 × 842
Legal	612 × 1008
A3	842 × 1190
Custom(w, h)	사용자 지정

고급 예제

주석이 포함된 다중 페이지 문서

use pdf_oxide::writer::{
    DocumentBuilder, DocumentMetadata, PageSize, StampType
};

let mut builder = DocumentBuilder::new()
    .metadata(
        DocumentMetadata::new()
            .title("Annotated Report")
            .author("Review Team")
    );

// Cover page
builder.page(PageSize::Letter)
    .at(72.0, 600.0)
    .font("Helvetica-Bold", 28.0)
    .text("Annual Review 2025")
    .font("Helvetica", 14.0)
    .space(20.0)
    .text("Prepared by the Review Team")
    .watermark_draft()
    .done();

// Content page with annotations
builder.page(PageSize::Letter)
    .at(72.0, 720.0)
    .heading(1, "Executive Summary")
    .paragraph(
        "Revenue increased 18% year-over-year, driven by expansion \
         into new markets and strong retention rates."
    )
    .text("See full financial details")
    .link_page(2)  // Link to page 3 (0-indexed)
    .space(12.0)
    .heading(2, "Key Findings")
    .text("Customer satisfaction reached an all-time high.")
    .highlight((1.0, 1.0, 0.0))  // Yellow highlight
    .sticky_note("Verify this claim with latest survey data")
    .paragraph(
        "Operating costs were reduced through automation initiatives, \
         achieving a 15% improvement in operational efficiency."
    )
    .stamp(StampType::ForComment)
    .done();

// Data page
builder.page(PageSize::Letter)
    .at(72.0, 720.0)
    .heading(1, "Financial Details")
    .paragraph("Detailed breakdown of revenue by segment...")
    .horizontal_rule()
    .paragraph("North America: $82M (+12%)")
    .paragraph("Europe: $41M (+28%)")
    .paragraph("Asia-Pacific: $19M (+35%)")
    .done();

builder.save("annotated_report.pdf")?;

정밀한 텍스트 위치 지정

use pdf_oxide::writer::{DocumentBuilder, PageSize};

let mut builder = DocumentBuilder::new();

builder.page(PageSize::Letter)
    // Title at top center area
    .at(200.0, 740.0)
    .font("Helvetica-Bold", 20.0)
    .text("Certificate of Completion")

    // Recipient name
    .at(200.0, 620.0)
    .font("Times-Roman", 16.0)
    .text("Awarded to: Jane Smith")

    // Details at specific positions
    .at(72.0, 500.0)
    .font("Helvetica", 12.0)
    .text("For successfully completing the Advanced Rust Programming course.")

    .at(72.0, 450.0)
    .text("Date: November 15, 2025")

    .at(350.0, 450.0)
    .text("Instructor: Dr. Alan Turing")

    .horizontal_rule()

    .at(72.0, 380.0)
    .font("Helvetica", 9.0)
    .text("Certificate ID: CERT-2025-00042")

    .done();

builder.save("certificate.pdf")?;

관련 페이지

• PdfBuilder 플루언트 API — PdfBuilder로 간편하게 PDF 만들기
• 주석 생성 — 모든 주석 유형 상세 설명
• 폼 필드 생성 — 대화형 폼 필드 추가
• 테이블 렌더링 — 테이블 만들기