Skip to content
PDF Oxide

PdfBuilder 流式 API

PdfBuilder 为 PDF 创建提供了流式配置 API。链式调用方法以设置页面尺寸、边距、字号、元数据等，然后调用 from_* 方法生成 PDF。

绑定支持情况。 流式 PdfBuilder / WasmPdfBuilder 在 Python、Rust 和 WASM 中公开。Go 和 C# 绑定提供了快捷入口点（FromMarkdown、FromHtml、FromImage / Pdf.FromMarkdown、Pdf.FromHtml、Pdf.FromText），但不公开构建器的配置接口。若要在 Go 或 C# 中使用自定义边距或页面尺寸，请使用命令行标志调用 Rust CLI，或封装一个通过 FFI 公开构建器的 Rust 辅助函数。

快速示例

Python

from pdf_oxide import Pdf

# Python uses optional keyword arguments on Pdf static methods
pdf = Pdf.from_markdown(
    "# Report\n\nContent here.",
    title="Quarterly Report",
    author="Finance Team"
)
pdf.save("report.pdf")

WASM

import { WasmPdf } from "pdf-oxide-wasm";

// JavaScript uses optional title and author parameters
const pdf = WasmPdf.fromMarkdown(
  "# Report\n\nContent here.",
  "Quarterly Report",
  "Finance Team"
);
writeFileSync("report.pdf", pdf.toBytes());

Rust

use pdf_oxide::api::PdfBuilder;
use pdf_oxide::writer::PageSize;

let pdf = PdfBuilder::new()
    .title("Quarterly Report")
    .author("Finance Team")
    .page_size(PageSize::A4)
    .margin(54.0)
    .font_size(11.0)
    .line_height(1.5)
    .from_markdown("# Report\n\nContent here.")?;

pdf.save("report.pdf")?;

完整 API 参考

构造函数

PdfBuilder::new() -> PdfBuilder

创建一个使用默认配置的新构建器：

设置项 默认值
页面尺寸 Letter (8.5" x 11")
所有边距 72pt (1 英寸)
字号 12pt
行高 1.5

元数据方法

.title(title) – 设置文档标题

PdfBuilder::new().title("My Document")

.author(author) – 设置文档作者

PdfBuilder::new().author("Jane Smith")

.subject(subject) – 设置文档主题

PdfBuilder::new().subject("Annual Performance Review")

.keywords(keywords) – 设置文档关键词

PdfBuilder::new().keywords("report, annual, 2025")

布局方法

.page_size(size) – 设置页面尺寸

use pdf_oxide::writer::PageSize;

PdfBuilder::new().page_size(PageSize::A4)

PageSize 枚举：

变体 尺寸
PageSize::Letter 612 x 792 pt (8.5" x 11")
PageSize::A4 595 x 842 pt (210 x 297 mm)
PageSize::Legal 612 x 1008 pt (8.5" x 14")
PageSize::A3 842 x 1190 pt (297 x 420 mm)
PageSize::Custom(w, h) 自定义宽度 x 高度（以磅为单位）

.margin(margin) – 设置统一边距

将四个边距（左、右、上、下）设置为相同的值（以磅为单位）。

PdfBuilder::new().margin(54.0)  // 0.75 inch margins

.margins(left, right, top, bottom) – 单独设置各边距

PdfBuilder::new().margins(72.0, 72.0, 54.0, 54.0)

排版方法

.font_size(size) – 设置默认字号

PdfBuilder::new().font_size(11.0)

.line_height(height) – 设置行高倍数

控制行间距。值为 1.5 表示字号的 1.5 倍。

PdfBuilder::new().line_height(1.6)

生成方法

每个生成方法都会消耗构建器并返回一个 Pdf 对象。

.from_markdown(content) – 从 Markdown 生成

let pdf = PdfBuilder::new()
    .title("Notes")
    .from_markdown("# Notes\n\n- Item one\n- Item two")?;

.from_html(content) – 从 HTML 生成

let pdf = PdfBuilder::new()
    .title("Report")
    .from_html("<h1>Report</h1><p>Summary of findings.</p>")?;

.from_text(content) – 从纯文本生成

let pdf = PdfBuilder::new()
    .font_size(10.0)
    .from_text("Line 1\nLine 2\nLine 3")?;

.from_image(path) – 从单张图片生成

let pdf = PdfBuilder::new()
    .page_size(PageSize::A4)
    .from_image("photo.jpg")?;

.from_image_bytes(data) – 从图片字节生成

let data = std::fs::read("chart.png")?;
let pdf = PdfBuilder::new().from_image_bytes(&data)?;

.from_images(paths) – 从多张图片生成

let pdf = PdfBuilder::new()
    .title("Photo Album")
    .from_images(&["img1.jpg", "img2.jpg", "img3.jpg"])?;

.from_qrcode(data) – 生成二维码 PDF

需要启用 barcodes 特性。

let pdf = PdfBuilder::new()
    .title("QR Code")
    .from_qrcode("https://example.com")?;

.from_barcode(barcode_type, data) – 生成条形码 PDF

需要启用 barcodes 特性。

use pdf_oxide::writer::barcode::BarcodeType;

let pdf = PdfBuilder::new()
    .from_barcode(BarcodeType::Code128, "ABC-12345")?;

高级示例

完整配置链

use pdf_oxide::api::PdfBuilder;
use pdf_oxide::writer::PageSize;

let content = r#"
# Technical Specification

## Overview

This document defines the interface contract for the v2 API.

## Endpoints

- `GET /api/v2/users` - List users
- `POST /api/v2/users` - Create user
- `GET /api/v2/users/:id` - Get user by ID

## Authentication

All endpoints require a Bearer token in the Authorization header.
"#;

let pdf = PdfBuilder::new()
    .title("API Specification v2")
    .author("Platform Team")
    .subject("REST API Technical Specification")
    .keywords("api, rest, specification, v2")
    .page_size(PageSize::A4)
    .margins(72.0, 72.0, 54.0, 72.0)
    .font_size(11.0)
    .line_height(1.5)
    .from_markdown(content)?;

pdf.save("api_spec.pdf")?;

自定义页面尺寸

use pdf_oxide::api::PdfBuilder;
use pdf_oxide::writer::PageSize;

// Create a half-letter page (5.5" x 8.5")
let pdf = PdfBuilder::new()
    .page_size(PageSize::Custom(396.0, 612.0))
    .margin(36.0)
    .font_size(10.0)
    .from_markdown("# Pocket Guide\n\nCompact reference card.")?;

pdf.save("pocket_guide.pdf")?;

JavaScript 等效用法

在 JavaScript/WASM 中，WasmPdf 静态方法接受可选的 title 和 author 参数，提供与 PdfBuilder 元数据相同的功能：

import { WasmPdf } from "pdf-oxide-wasm";

const pdf = WasmPdf.fromMarkdown("# Notes\n\n- Item one\n- Item two", "Notes");
const html = WasmPdf.fromHtml("<h1>Report</h1><p>Summary.</p>", "Report", "Author");
const text = WasmPdf.fromText("Line 1\nLine 2", "Plain Text Doc");
const img = WasmPdf.fromImageBytes(imageData);

WASM API 中不提供页面尺寸、边距、字号和行高配置——请使用默认布局设置。

输出方法

获得 Pdf / WasmPdf 对象后，使用以下方法进行输出：

方法 语言 说明
.save(path) Python, Rust 将 PDF 写入文件
.to_bytes() (Python) Python 获取原始 PDF 字节
.into_bytes() (Rust) Rust 消耗 Pdf 并返回 Vec<u8>
.toBytes() (JS) JavaScript 以 Uint8Array 形式获取 PDF

相关页面