DocumentBuilder Fluent-API

DocumentBuilder ist eine fluente API, mit der Sie PDF-Dokumente Seite für Seite aufbauen — mit voller Kontrolle über Textplatzierung, Fonts, Anmerkungen, Formularfelder und Inhaltsbausteine.

Binding-Abdeckung (v0.3.38). DocumentBuilder + FluentPageBuilder + EmbeddedFont gibt es in Rust, Python, Node/TypeScript, C#, Go und WASM. Jede Sprachanbindung bietet dieselbe Oberfläche: mehrseitige Konstruktion, CJK- / Kyrillisch- / Griechisch-Text über eingebettete Fonts, 15 Anmerkungsmethoden, 5 AcroForm-Widget-Typen, Grafik-Primitive (rect, filled_rect, line), AES-256-Verschlüsselung sowie die HTML+CSS-Pipeline.

Schnellbeispiel

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-Pfad; setzt CGO_ENABLED=1 voraus)

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 (Browser / Node / Bundler — gleiche 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();

Vollständige API-Referenz

DocumentBuilder

DocumentBuilder::new() — Builder erstellen

let mut builder = DocumentBuilder::new();

.metadata(metadata) — Dokument-Metadaten setzen

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) — Seite hinzufügen

Gibt einen FluentPageBuilder zum Hinzufügen von Inhalten zur Seite zurück. Rufen Sie .done() auf, wenn die Seite fertig ist.

use pdf_oxide::writer::PageSize;

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

.letter_page() / .a4_page() — Bequeme Seitenmethoden

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

.build() — PDF-Bytes erzeugen

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

.save(path) — Bauen und in Datei speichern

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

.save_encrypted(path, user_pw, owner_pw) — AES-256-Verschlüsselung

Neu in v0.3.38. In jeder Sprachanbindung verfügbar.

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");

Ebenfalls verfügbar: .to_bytes_encrypted(user_pw, owner_pw) für eine Ausgabe im Speicher sowie .save_with_encryption(path, algorithm, permissions, user_pw, owner_pw) (nur Rust) für eigene Algorithmen und feingranulare Berechtigungen.

DocumentMetadata

Builder für Metadaten auf Dokumentebene.

Methode	Beschreibung
.title(s)	Dokumenttitel setzen
.author(s)	Autor setzen
.subject(s)	Betreff setzen
.keywords(s)	Schlüsselwörter setzen
.creator(s)	Erzeugende Anwendung setzen

FluentPageBuilder

Wird von builder.page(size) zurückgegeben. Alle Methoden geben self zum Verketten zurück — außer .done().

Text und Positionierung

Methode	Beschreibung
.at(x, y)	Cursorposition setzen (Punkte, vom unteren linken Rand)
.text(s)	Text an aktueller Cursorposition einfügen
.heading(level, s)	Überschrift (1–6, mit passender Schrift) einfügen
.paragraph(s)	Absatz mit automatischem Zeilenumbruch einfügen
.font(name, size)	Font für folgenden Text setzen
.text_config(config)	Vollständige Textkonfiguration setzen
.space(points)	Vertikalen Abstand einfügen
.horizontal_rule()	Horizontale Trennlinie einfügen
.element(elem)	Rohes ContentElement einfügen
.elements(vec)	Mehrere rohe Inhaltselemente einfügen

Anmerkungen

Methode	Beschreibung
.link_url(url)	Letztes Textelement mit einer URL verknüpfen
.link_page(page_index)	Letzten Text mit interner Seite verknüpfen
.link_named(destination)	Mit benanntem Ziel verknüpfen
.highlight(color)	Letzten Text hervorheben (RGB-Tripel)
.underline(color)	Letzten Text unterstreichen
.strikeout(color)	Letzten Text durchstreichen
.squiggly(color)	Letzten Text mit Wellenlinie versehen
.sticky_note(text)	Notiz an Cursorposition einfügen
.sticky_note_with_icon(text, icon)	Notiz mit bestimmtem Icon einfügen
.sticky_note_at(x, y, text)	Notiz an bestimmter Position einfügen
.stamp(stamp_type)	Stempel an Cursorposition einfügen
.stamp_at(rect, stamp_type)	Stempel in bestimmtem Rechteck einfügen
.freetext(rect, text)	Freitext-Anmerkung einfügen
.freetext_styled(rect, text, font, size)	Gestaltete Freitext-Anmerkung einfügen
.watermark(text)	Diagonales Wasserzeichen über die Seite legen
.watermark_confidential()	Voreingestelltes “CONFIDENTIAL”-Wasserzeichen
.watermark_draft()	Voreingestelltes “DRAFT”-Wasserzeichen
.watermark_custom(watermark)	Benutzerdefiniertes Wasserzeichen einfügen
.add_annotation(annotation)	Beliebigen Anmerkungstyp einfügen

AcroForm-Widgets

In v0.3.38 in allen Bindings hinzugekommen. Alle Positionen sind in PDF-Punkten, gemessen vom unteren linken Ursprung der Seite.

Methode	Beschreibung
.text_field(name, x, y, w, h, default_value=None)	Einzeiliges Texteingabefeld
.checkbox(name, x, y, w, h, checked)	Kontrollkästchen
.combo_box(name, x, y, w, h, options, selected=None)	Auswahl-Dropdown
.radio_group(name, buttons, selected=None)	Radiogruppe; buttons ist eine Liste (export_value, x, y, w, h)
.push_button(name, x, y, w, h, caption)	Anklickbare Schaltfläche mit Beschriftung

(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"))

Grafik-Primitive

In v0.3.38 in allen Bindings hinzugekommen: rect(x, y, w, h) (nur Umriss), filled_rect(x, y, w, h, color) (gefüllt, RGB-Tripel) und line(x1, y1, x2, y2). Sie reihen sich in dieselbe FluentPageBuilder-Kette ein und reichen für Formularhintergründe, Trennlinien und einfache Tabellenrahmen.

Für volle Kontrolle über Pfade, Muster, Verläufe und ExtGState greifen Sie zu ContentStreamBuilder (nur Rust — siehe Grafik, Muster und Shadings).

.done() — Seite abschließen

Gibt die Kontrolle an den DocumentBuilder zurück.

builder.page(PageSize::Letter)
    .at(72.0, 720.0)
    .text("Content")
    .done();  // Zurück zum Builder

TextConfig

Konfiguration für das Textrendering.

use pdf_oxide::writer::TextConfig;

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

Feld	Typ	Standard
font	String	"Helvetica"
size	f32	12.0
align	TextAlign	Left
line_height	f32	1.2

PageSize

Variante	Breite × Höhe (Punkte)
Letter	612 × 792
A4	595 × 842
Legal	612 × 1008
A3	842 × 1190
Custom(w, h)	Eigene Abmessungen

Weiterführende Beispiele

Mehrseitiges Dokument mit Anmerkungen

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")?;

Präzise Textpositionierung

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")?;

Verwandte Seiten

• PdfBuilder Fluent-API — Erstellung auf hohem Niveau mit PdfBuilder
• Anmerkungen erstellen — Alle Anmerkungstypen im Detail
• Formularfelder erstellen — Interaktive Formularfelder einfügen
• Tabellen rendern — Tabellen erzeugen