Текучий 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();
C++
#include <pdf_oxide/pdf_oxide.hpp>
auto font = pdf_oxide::EmbeddedFont::from_file("DejaVuSans.ttf");
auto builder = pdf_oxide::DocumentBuilder::create();
builder.register_embedded_font("DejaVu", font);
builder.a4_page()
.font("DejaVu", 12).at(72, 720).text("Hello, World!")
.highlight(1.0, 1.0, 0.0)
.done();
std::vector<std::uint8_t> bytes = builder.build();
Swift
import PdfOxide
let font = try EmbeddedFont.fromFile("DejaVuSans.ttf")
let builder = try DocumentBuilder.create()
try builder.registerEmbeddedFont("DejaVu", font)
let page = try builder.a4Page()
try page.font("DejaVu", 12).at(72, 720).text("Hello, World!")
.highlight(1.0, 1.0, 0.0)
.done()
let bytes = try builder.build()
Dart
import 'package:pdf_oxide/pdf_oxide.dart';
final font = EmbeddedFont.fromFile('DejaVuSans.ttf');
final builder = DocumentBuilder.create();
builder.registerEmbeddedFont('DejaVu', font);
builder.a4Page()
.font('DejaVu', 12.0).at(72.0, 720.0).text('Hello, World!')
.highlight(1.0, 1.0, 0.0)
.done();
final bytes = builder.build();
R
library(pdfoxide)
font <- pdf_embedded_font_from_file("DejaVuSans.ttf")
b <- pdf_builder_create()
pdf_builder_register_embedded_font(b, "DejaVu", font)
pg <- pdf_builder_a4_page(b)
pdf_page_font(pg, "DejaVu", 12)
pdf_page_at(pg, 72, 720)
pdf_page_builder_text(pg, "Hello, World!")
pdf_page_highlight(pg, 1.0, 1.0, 0.0)
pdf_page_done(pg)
bytes <- pdf_builder_build(b)
Julia
using PdfOxide
emb = embedded_font_from_file("DejaVuSans.ttf")
b = DocumentBuilder()
register_embedded_font(b, "DejaVu", emb)
pg = a4_page(b)
font(pg, "DejaVu", 12)
at(pg, 72, 720)
text(pg, "Hello, World!")
highlight(pg, 1.0, 1.0, 0.0)
done(pg)
bytes = build(b)
Zig
const pdf_oxide = @import("pdf_oxide");
const a = std.heap.page_allocator;
var font = try pdf_oxide.EmbeddedFont.fromFile("DejaVuSans.ttf");
var builder = try pdf_oxide.DocumentBuilder.create();
try builder.registerEmbeddedFont("DejaVu", &font);
var page = try builder.a4Page();
try page.font("DejaVu", 12);
try page.at(72, 720);
try page.text("Hello, World!");
try page.highlight(1.0, 1.0, 0.0);
try page.done();
const bytes = try builder.build(a);
Objective-C
#import "POXPdfOxide.h"
NSError *err = nil;
POXEmbeddedFont *font = [POXEmbeddedFont fromPath:@"DejaVuSans.ttf" error:&err];
POXDocumentBuilder *builder = [POXDocumentBuilder createWithError:&err];
[builder registerEmbeddedFont:@"DejaVu" font:font error:&err];
POXPageBuilder *page = [builder a4PageWithError:&err];
[page font:@"DejaVu" size:12 error:&err];
[page at:72 y:720 error:&err];
[page text:@"Hello, World!" error:&err];
[page highlightR:1.0 g:1.0 b:0.0 error:&err];
[page done:&err];
NSData *bytes = [builder buildWithError:&err];
Elixir
{:ok, font} = PdfOxide.font_from_file("DejaVuSans.ttf")
{:ok, db} = PdfOxide.builder()
:ok = PdfOxide.builder_register_embedded_font(db, "DejaVu", font)
{:ok, page} = PdfOxide.builder_a4_page(db)
:ok = PdfOxide.page_font(page, "DejaVu", 12)
:ok = PdfOxide.page_at(page, 72, 720)
:ok = PdfOxide.page_text(page, "Hello, World!")
:ok = PdfOxide.page_highlight(page, 1.0, 1.0, 0.0)
:ok = PdfOxide.page_done(page)
{:ok, bytes} = PdfOxide.builder_build(db)
Полный справочник 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
Строитель метаданных уровня документа.
| Метод | Описание |
|---|---|
.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(); // 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
| Вариант | Ширина x Высота (пункты) |
|---|---|
Letter |
612 x 792 |
A4 |
595 x 842 |
Legal |
612 x 1008 |
A3 |
842 x 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
- Создание аннотаций – Все типы аннотаций подробно
- Создание полей форм – Добавление интерактивных полей форм
- Отрисовка таблиц – Создание таблиц