Skip to content
PDF Oxide

二维码与条码

直接生成二维码和一维条码为 PDF 文档。条码生成功能在 feature flag 后面，以保持核心库的轻量。

需要功能标志： barcodes

# Cargo.toml
[dependencies]
pdf_oxide = { version = "0.3", features = ["barcodes"] }

快速示例

Python

from pdf_oxide import Pdf

# QR code
pdf = Pdf.from_qrcode("https://example.com")
pdf.save("qrcode.pdf")

# Barcode
pdf = Pdf.from_barcode("Code128", "ABC-12345")
pdf.save("barcode.pdf")

Rust

use pdf_oxide::api::Pdf;

// QR code
let pdf = Pdf::from_qrcode("https://example.com")?;
pdf.save("qrcode.pdf")?;

// Barcode
use pdf_oxide::writer::barcode::BarcodeType;
let pdf = Pdf::from_barcode(BarcodeType::Code128, "ABC-12345")?;
pdf.save("barcode.pdf")?;

完整 API 参考

QR Code Generation

Pdf::from_qrcode(data) – 默认二维码

创建一个包含 300px 二维码的单页 PDF。

Rust：

use pdf_oxide::api::Pdf;

let pdf = Pdf::from_qrcode("https://example.com")?;
pdf.save("qr.pdf")?;

Python：

from pdf_oxide import Pdf

pdf = Pdf.from_qrcode("https://example.com")
pdf.save("qr.pdf")

Python 签名：

Pdf.from_qrcode(data: str) -> Pdf

Pdf::from_qrcode_with_options(data, options) – 自定义二维码

完全控制大小、纠错级别、颜色和静区。

Rust：

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::barcode::{QrCodeOptions, QrErrorCorrection};

let options = QrCodeOptions::new()
    .size(400)
    .error_correction(QrErrorCorrection::High)
    .quiet_zone(6)
    .foreground(0, 0, 128, 255)          // Navy blue
    .background(255, 255, 255, 255);     // White

let pdf = Pdf::from_qrcode_with_options("https://example.com", &options)?;
pdf.save("custom_qr.pdf")?;

QrCodeOptions – 二维码配置

Method 默认值 描述
.size(px) 200 二维码大小（像素）
.error_correction(level) Medium 纠错级别
.quiet_zone(modules) 4 模块中的边框宽度
.foreground(r, g, b, a) Black (0,0,0,255) 模块颜色（RGBA）
.background(r, g, b, a) White (255,255,255,255) 背景颜色（RGBA）

QrErrorCorrection Enum

变体 恢复能力 用例
Low ~7% 最大数据密度
Medium ~15% 通用（默认）
Quartile ~25% 可能损坏的标签
High ~30% 工业/恶劣环境

1D Barcode Generation

Pdf::from_barcode(barcode_type, data) – 默认条码

使用默认大小（200x80）创建包含条码的单页 PDF。

Rust：

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::barcode::BarcodeType;

let pdf = Pdf::from_barcode(BarcodeType::Ean13, "5901234123457")?;
pdf.save("product.pdf")?;

Python：

from pdf_oxide import Pdf

# Barcode type as string: "code128", "ean13", "upca", "code39", "ean8", "itf"
pdf = Pdf.from_barcode("ean13", "5901234123457")
pdf.save("product.pdf")

Python 签名：

Pdf.from_barcode(
    barcode_type: str,  # "code128" | "ean13" | "upca" | "code39" | "ean8" | "itf"
    data: str
) -> Pdf

Pdf::from_barcode_with_options(barcode_type, data, options) – 自定义条码

完全控制条码尺寸和颜色。

Rust：

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::barcode::{BarcodeType, BarcodeOptions};

let options = BarcodeOptions::new()
    .width(400)
    .height(120)
    .foreground(0, 0, 0, 255)
    .background(255, 255, 255, 255);

let pdf = Pdf::from_barcode_with_options(
    BarcodeType::Code128,
    "SHIP-2025-00042",
    &options,
)?;
pdf.save("shipping_label.pdf")?;

BarcodeOptions – 一维码配置

Method 默认值 描述
.width(px) 200 条码宽度（像素）
.height(px) 80 条码高度（像素）
.foreground(r, g, b, a) Black (0,0,0,255) 条纹颜色（RGBA）
.background(r, g, b, a) White (255,255,255,255) 背景颜色（RGBA）
.show_text(bool) false 显示人类可读文本

BarcodeType Enum

变体 名称 数据格式
Code128 Code 128 字母数字（自动选择 A/B/C）
Code39 Code 39 大写字母数字 + 符号
Ean13 EAN-13 13 位数字（欧洲商品编号）
Ean8 EAN-8 8 位数字（紧凑 EAN）
UpcA UPC-A 11-12 位数字（通用产品代码）
Itf Interleaved 2 of 5 数字对（偶数位数）
Code93 Code 93 字母数字（紧凑）
Codabar Codabar 数字 + 特殊字符（A-D 起止）

底层 BarcodeGenerator

生成条码图片而不创建完整 PDF（例如嵌入到现有文档中）：

use pdf_oxide::writer::barcode::{BarcodeGenerator, BarcodeType, BarcodeOptions, QrCodeOptions};

// Generate QR code as PNG bytes
let qr_png = BarcodeGenerator::generate_qr(
    "https://example.com",
    &QrCodeOptions::default().size(256),
)?;

// Generate QR code with simple API
let qr_png = BarcodeGenerator::generate_qr_simple("https://example.com", 200)?;

// Generate 1D barcode as PNG bytes
let barcode_png = BarcodeGenerator::generate_1d(
    BarcodeType::Code128,
    "ABC123",
    &BarcodeOptions::default().width(300).height(100),
)?;

// Convenience methods
let code128_png = BarcodeGenerator::generate_code128("DATA", 200, 80)?;
let ean13_png = BarcodeGenerator::generate_ean13("5901234123457", 200, 80)?;

使用 PdfBuilder 处理条码

PdfBuilder 提供流畅的接口，在生成条码 PDF 之前设置页面大小和文档元数据。

use pdf_oxide::api::PdfBuilder;
use pdf_oxide::writer::PageSize;
use pdf_oxide::writer::barcode::{BarcodeType, QrCodeOptions, QrErrorCorrection};

// QR code with custom page size
let pdf = PdfBuilder::new()
    .title("WiFi Access")
    .page_size(PageSize::Custom(300.0, 300.0))
    .from_qrcode("WIFI:T:WPA;S:MyNetwork;P:secret123;;")?;
pdf.save("wifi_qr.pdf")?;

// Barcode with metadata
let pdf = PdfBuilder::new()
    .title("Product Label")
    .author("Warehouse System")
    .from_barcode(BarcodeType::Ean13, "5901234123457")?;
pdf.save("label.pdf")?;

高级示例

带多个条码的运单标签

use pdf_oxide::writer::barcode::{BarcodeGenerator, BarcodeType, BarcodeOptions, QrCodeOptions};
use pdf_oxide::writer::{PdfWriter, PdfWriterConfig};
use pdf_oxide::geometry::Rect;

// Generate barcode images
let tracking_barcode = BarcodeGenerator::generate_code128(
    "1Z999AA10123456784",
    300,
    80,
)?;

let qr_bytes = BarcodeGenerator::generate_qr(
    "https://track.example.com/1Z999AA10123456784",
    &QrCodeOptions::new().size(200).error_correction(QrErrorCorrection::Medium),
)?;

// These PNG bytes can then be embedded in a PDF using the image APIs

批量生成产品标签

use pdf_oxide::api::Pdf;
use pdf_oxide::writer::barcode::BarcodeType;

let products = vec![
    ("5901234123457", "Widget A"),
    ("4006381333931", "Widget B"),
    ("0012345678905", "Widget C"),
];

for (ean, name) in products {
    let pdf = Pdf::from_barcode(BarcodeType::Ean13, ean)?;
    pdf.save(format!("label_{}.pdf", name.to_lowercase().replace(' ', "_")))?;
}

Python：生成并保存二维码

from pdf_oxide import Pdf

urls = [
    "https://example.com/product/1",
    "https://example.com/product/2",
    "https://example.com/product/3",
]

for i, url in enumerate(urls):
    pdf = Pdf.from_qrcode(url)
    pdf.save(f"qr_product_{i + 1}.pdf")

Python：批量条码生成

from pdf_oxide import Pdf

items = [
    ("code128", "SHIP-00001"),
    ("code128", "SHIP-00002"),
    ("ean13", "5901234123457"),
    ("upca", "012345678905"),
]

for barcode_type, data in items:
    pdf = Pdf.from_barcode(barcode_type, data)
    pdf.save(f"barcode_{data}.pdf")

功能标志

barcodes 功能引入两个额外依赖：

  • barcoders – 1D barcode encoding
  • qrcode – QR code encoding

不启用 feature flag 时，所有条码方法返回一条错误消息，提示需要该功能。

// Without the barcodes feature enabled:
let result = Pdf::from_qrcode("test");
// Returns Err("QR code generation requires the 'barcodes' feature")

相关页面