Вільний API DocumentBuilder

DocumentBuilder — це вільний (fluent) API для покрокового конструювання PDF-документів сторінка за сторінкою з повним контролем над розміщенням тексту, шрифтами, анотаціями, полями форм і елементами вмісту.

Охоплення прив’язок (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) для результату в пам’яті; .save_with_encryption(path, algorithm, permissions, user_pw, owner_pw) (Rust) — з вибором алгоритму та перемикачами дозволів.

DocumentMetadata

Білдер для метаданих на рівні документа.

Method	Опис
.title(s)	Встановити назву документа
.author(s)	Встановити автора документа
.subject(s)	Встановити тему документа
.keywords(s)	Встановити ключові слова
.creator(s)	Встановити застосунок-творець

FluentPageBuilder

Повертається з builder.page(size). Усі методи повертають self для ланцюжка (окрім .done()).

Текст і позиціювання

Method	Опис
.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)	Додати кілька сирих елементів вмісту

Анотації

Method	Опис
.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 від нижнього лівого кута сторінки.

Method	Опис
.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();  // Back to builder

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

Варіант	Ширина × Висота (пункти)
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")?;

Пов’язані сторінки

• Вільний API PdfBuilder — високорівневе створення через PdfBuilder
• Створення анотацій — усі типи анотацій детально
• Створення полів форм — додавання інтерактивних полів
• Рендер таблиць — створення таблиць