Skip to content

DocumentBuilder 流式 API

DocumentBuilder 提供一个流式 API,用于逐页构建 PDF 文档,完全控制文本放置、字体、注释、表单字段和内容元素。

绑定覆盖(v0.3.38)。 DocumentBuilder + FluentPageBuilder + EmbeddedFont 已在 Rust、Python、Node/TypeScript、C#、Go 和 WASM 中提供。每个绑定都暴露相同的 API:多页构建、通过嵌入字体实现 CJK / 西里尔 / 希腊文文本、15 个注释方法、5 种 AcroForm 控件、图形基元(rectfilled_rectline)、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() 除外)。

Text and Positioning

Method 描述
.at(x, y) 设置光标位置(从左下角算起的磅值)
.text(s) 在当前光标位置添加文本
.heading(level, s) Add heading (1-6, with appropriate font)
.paragraph(s) 添加带自动换行的段落
.font(name, size) 设置后续文本的字体
.text_config(config) 设置完整文本配置
.space(points) 添加垂直间距
.horizontal_rule() Add a horizontal divider line
.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,
};
Field Type 默认值
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) Custom dimensions

高级示例

带注释的多页文档

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

相关页面