QR-коды и штрихкоды

Генерируйте QR-коды и одномерные штрихкоды напрямую в виде PDF-документов, как отдельные изображения PNG/SVG или размещайте их на страницах существующего PDF. Генерация штрихкодов скрыта за флагом функции, чтобы основная библиотека оставалась лёгкой.

Покрытие в привязках. Существует два различных набора возможностей для штрихкодов:

1. Одношаговые конструкторы PDF (Pdf::from_qrcode / Pdf::from_barcode) и низкоуровневый BarcodeGenerator — доступны только в Rust.
2. Семейство дескрипторов изображений штрихкодов (generate_qr_code, generate_barcode, add_barcode_to_page), опирающееся на функции C ABI pdf_generate_qr_code / pdf_generate_barcode / pdf_add_barcode_to_page — доступно в Swift, Go и C#, а также может вызываться напрямую из C/C++ через FFI.
3. Генераторы SVG (generate_qr_svg / generate_barcode_svg) — доступны в Python и Rust.

Каждый метод ниже помечен языками, которые его действительно предоставляют. Не предполагайте, что метод существует в привязке, где он не показан.

Требуется флаг функции: barcodes

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

Как сгенерировать QR-код в виде PDF?

Самый быстрый путь в Rust — одношаговый конструктор Pdf::from_qrcode. pdf_oxide записывает QR-код в одностраничный PDF, который можно сразу сохранить.

Rust:

use pdf_oxide::api::Pdf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // QR code (300px) -> single-page PDF
    let pdf = Pdf::from_qrcode("https://example.com")?;
    pdf.save("qrcode.pdf")?;

    // 1D barcode -> single-page PDF
    use pdf_oxide::writer::barcode::BarcodeType;
    let pdf = Pdf::from_barcode(BarcodeType::Code128, "ABC-12345")?;
    pdf.save("barcode.pdf")?;
    Ok(())
}

Как сгенерировать изображение штрихкода (PNG/SVG) вместо PDF?

Когда вам нужен закодированный глиф в виде изображения — чтобы встроить его в существующий документ, передать на веб-фронтенд или напечатать на этикетке — используйте семейство дескрипторов изображений или генераторы SVG. Канонические имена методов — generate_qr_code и generate_barcode (старые имена generate_qr / generate_code не входят в публичный интерфейс).

Swift (BarcodeImage.generateQrCode, BarcodeImage.generateBarcode):

import PdfOxide

// QR code. errorCorrection: 0=L 1=M 2=Q 3=H. sizePx: module-grid pixel size.
let qr = try BarcodeImage.generateQrCode("https://example.com",
                                         errorCorrection: 1, sizePx: 256)
let pngBytes = try qr.imagePng(sizePx: 256)   // [UInt8]
let svg      = try qr.svg(sizePx: 256)        // String
qr.close()

// 1D barcode. format: 0=Code128 1=Code39 2=EAN13 3=EAN8 4=UPCA 5=ITF 6=Code93 7=Codabar.
let bc = try BarcodeImage.generateBarcode("5901234123457", format: 2, sizePx: 256)
let barcodePng = try bc.imagePng(sizePx: 256)
bc.close()

Go (GenerateQRCode, GenerateBarcode):

package main

import (
	"os"

	pdfoxide "github.com/yfedoseev/pdf_oxide/go"
)

func main() {
	// QR code. errorCorrection: 0=Low 1=Medium 2=Quartile 3=High.
	qr, err := pdfoxide.GenerateQRCode("https://example.com", 1, 256)
	if err != nil {
		panic(err)
	}
	defer qr.Close()
	svg, _ := qr.SVGData()
	_ = os.WriteFile("qr.svg", []byte(svg), 0o644)

	// 1D barcode. format: 0=Code128 1=Code39 2=EAN13 3=EAN8 4=UPCA 5=ITF 6=Code93 7=Codabar.
	bc, err := pdfoxide.GenerateBarcode("5901234123457", 2, 300)
	if err != nil {
		panic(err)
	}
	defer bc.Close()
	png, _ := bc.PNGData()
	_ = os.WriteFile("ean13.png", png, 0o644)
}

C# (Barcode.GenerateQrCode, Barcode.Generate):

using PdfOxide;

// QR code. errorCorrection: 0=L 1=M 2=Q 3=H. sizePx default 300.
using var qr = Barcode.GenerateQrCode("https://example.com", errorCorrection: 1, sizePx: 256);
byte[] qrPng = qr.ToPng(256);
string qrSvg = qr.ToSvg();

// 1D barcode. BarcodeFormat: Code128, Code39, Ean13, Ean8, UpcA, Itf.
using var bc = Barcode.Generate("5901234123457", BarcodeFormat.Ean13, sizePx: 300);
byte[] eanPng = bc.ToPng(300);

Python (generate_qr_svg, generate_barcode_svg — только SVG):

import pdf_oxide

# QR code SVG. error_correction: 0=Low, 1=Medium, 2=Quartile, 3=High. size in px.
qr_svg = pdf_oxide.generate_qr_svg("https://example.com", 1, 256)
with open("qr.svg", "w") as f:
    f.write(qr_svg)

# 1D barcode SVG. barcode_type: 0=Code128, 1=Code39, 2=EAN13, 3=EAN8,
#                                4=UPCA, 5=ITF, 6=Code93, 7=Codabar.
ean_svg = pdf_oxide.generate_barcode_svg(2, "5901234123457")
with open("ean13.svg", "w") as f:
    f.write(ean_svg)

Как добавить штрихкод на страницу существующего PDF?

Используйте add_barcode_to_page, чтобы разместить сгенерированное изображение штрихкода на странице (с индексом от 0) объекта DocumentEditor в заданной позиции и заданного размера, а затем сохранить документ. Этот метод идиоматично доступен в Swift как DocumentEditor.addBarcodeToPage и напрямую через C ABI как pdf_add_barcode_to_page. Семейство дескрипторов изображений, от которого он зависит, не обёрнуто в классах редактора Go/C#, поэтому для размещения на месте используйте Swift (или вызывайте C ABI из C/C++).

Swift (DocumentEditor.addBarcodeToPage):

import PdfOxide

let editor = try DocumentEditor.openFromBytes(try Data(contentsOf: inputURL).map { $0 })

// Generate the barcode image, then stamp it onto page 0 (PDF user-space points).
let qr = try BarcodeImage.generateQrCode("https://example.com/track/42", sizePx: 128)
try editor.addBarcodeToPage(0, qr, x: 36, y: 36, width: 96, height: 96)

let outBytes = try editor.saveToBytes()
qr.close()
editor.close()

C ABI (pdf_add_barcode_to_page):

#include "pdf_oxide.h"

int err = 0;

// Build a barcode handle (QR shown; use pdf_generate_barcode for 1D).
FfiBarcodeImage *qr = pdf_generate_qr_code("https://example.com/track/42",
                                           /*error_correction=*/1,
                                           /*size_px=*/128, &err);

// Place it on page 0 at (x, y) sized width x height (PDF user-space points).
pdf_add_barcode_to_page(editor, /*page_index=*/0, qr,
                        /*x=*/36.0f, /*y=*/36.0f,
                        /*width=*/96.0f, /*height=*/96.0f, &err);

pdf_barcode_free(qr);

Сигнатуры методов

Одношаговые конструкторы PDF — только Rust

// QR code, 300px default size:
Pdf::from_qrcode(data: &str) -> Result<Pdf>
Pdf::from_qrcode_with_options(data: &str, options: &QrCodeOptions) -> Result<Pdf>

// 1D barcode, 200x80 default size:
Pdf::from_barcode(barcode_type: BarcodeType, data: &str) -> Result<Pdf>
Pdf::from_barcode_with_options(barcode_type: BarcodeType, data: &str,
                               options: &BarcodeOptions) -> Result<Pdf>

Семейство дескрипторов изображений штрихкодов — Swift / Go / C# / C ABI

Язык	Генератор QR	Генератор 1D	Размещение на странице
Swift	BarcodeImage.generateQrCode(_ data:, errorCorrection: Int32 = 1, sizePx: Int32 = 256)	BarcodeImage.generateBarcode(_ data:, format: Int32, sizePx: Int32 = 256)	DocumentEditor.addBarcodeToPage(_ page:, _ barcode:, x:, y:, width:, height:)
Go	GenerateQRCode(data string, errorCorrection int, sizePx int) (*BarcodeImage, error)	GenerateBarcode(data string, format int, sizePx int) (*BarcodeImage, error)	— (не обёрнуто в редакторе)
C#	Barcode.GenerateQrCode(string data, int errorCorrection = 1, int sizePx = 300)	Barcode.Generate(string data, BarcodeFormat format = Code128, int sizePx = 300)	— (не обёрнуто в редакторе)
C ABI	pdf_generate_qr_code(const char *data, int32_t error_correction, int32_t size_px, int32_t *error_code)	pdf_generate_barcode(const char *data, int32_t format, int32_t size_px, int32_t *error_code)	pdf_add_barcode_to_page(DocumentEditor *doc, int32_t page_index, const FfiBarcodeImage *barcode, float x, float y, float width, float height, int32_t *error_code)

Получив дескриптор штрихкода, вы можете прочитать его полезную нагрузку и отрисовать его:

Операция	Swift	Go	C#	C ABI
Байты PNG	imagePng(sizePx:)	PNGData()	ToPng(sizePx)	pdf_barcode_get_image_png
Строка SVG	svg(sizePx:)	SVGData()	ToSvg()	pdf_barcode_get_svg
Декодированные данные	data()	SourceData()	Data	pdf_barcode_get_data
Код формата	format()	—	Format	pdf_barcode_get_format
Освобождение дескриптора	close()	Close()	Dispose()	pdf_barcode_free

Генераторы SVG — Python / Rust

# Python free functions (require the barcodes feature in the wheel):
generate_qr_svg(data: str, error_correction: int, size: int) -> str
generate_barcode_svg(barcode_type: int, data: str) -> str

Rust: полный справочник по API

Генерация QR-кодов

Pdf::from_qrcode(data) — QR-код по умолчанию

Создаёт одностраничный PDF с QR-кодом размером 300px.

use pdf_oxide::api::Pdf;

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

Pdf::from_qrcode_with_options(data, options) — настраиваемый QR-код

Полный контроль над размером, коррекцией ошибок, цветами и зоной тишины.

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 — конфигурация QR

Метод	По умолчанию	Описание
.size(px)	200	Размер QR-кода в пикселях
.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

Вариант	Способность к восстановлению	Сценарий использования	Целое число (FFI)
Low	~7%	Максимальная плотность данных	0
Medium	~15%	Общего назначения (по умолчанию)	1
Quartile	~25%	Этикетки, которые могут повредиться	2
High	~30%	Промышленная / суровая среда	3

Генерация одномерных штрихкодов

Pdf::from_barcode(barcode_type, data) — штрихкод по умолчанию

Создаёт одностраничный PDF со штрихкодом, используя размер по умолчанию (200x80).

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

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

Pdf::from_barcode_with_options(barcode_type, data, options) — настраиваемый штрихкод

Полный контроль над размерами и цветами штрихкода.

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 — конфигурация 1D

Метод	По умолчанию	Описание
.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

Вариант	Название	Формат данных	Целое число (FFI)
Code128	Code 128	Буквенно-цифровой (автовыбор A/B/C)	0
Code39	Code 39	Прописные буквы и цифры + символы	1
Ean13	EAN-13	13 цифр (European Article Number)	2
Ean8	EAN-8	8 цифр (компактный EAN)	3
UpcA	UPC-A	11–12 цифр (Universal Product Code)	4
Itf	Interleaved 2 of 5	Пары цифр (чётное число цифр)	5
Code93	Code 93	Буквенно-цифровой (компактный)	6
Codabar	Codabar	Цифры + специальные символы (старт/стоп A-D)	7

C ABI pdf_generate_barcode и обёртки Go/Swift/C# выбирают символику по столбцу Целое число (FFI) выше. Перечисление BarcodeFormat в C# сейчас предоставляет Code128–Itf (0–5).

Низкоуровневый BarcodeGenerator — только Rust

Для генерации изображений штрихкодов без создания полноценного 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 as an SVG string
let qr_svg = BarcodeGenerator::generate_qr_svg(
    "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),
)?;

// Generate 1D barcode as an SVG string
let barcode_svg = BarcodeGenerator::generate_1d_svg(
    BarcodeType::Code128,
    "ABC123",
    &BarcodeOptions::default(),
)?;

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

Использование PdfBuilder со штрихкодами — только Rust

PdfBuilder предоставляет текучий интерфейс для задания размера страницы и метаданных документа перед генерацией PDF со штрихкодами.

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

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

Продвинутые примеры

Транспортная этикетка с несколькими штрихкодами (Rust)

use pdf_oxide::writer::barcode::{BarcodeGenerator, QrCodeOptions, QrErrorCorrection};

// Generate barcode images, then embed via the image APIs.
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),
)?;

// `tracking_barcode` and `qr_bytes` are PNG byte vectors ready to embed.

Пакетная генерация этикеток для товаров (Rust)

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(' ', "_")))?;
}

Пакетная генерация SVG штрихкодов (Python)

import pdf_oxide

items = [
    (0, "SHIP-00001"),   # Code128
    (0, "SHIP-00002"),   # Code128
    (2, "5901234123457"),  # EAN-13
    (4, "012345678905"),   # UPC-A
]

for barcode_type, data in items:
    svg = pdf_oxide.generate_barcode_svg(barcode_type, data)
    with open(f"barcode_{data}.svg", "w") as f:
        f.write(svg)

Нанесение QR-кодов отслеживания на каждую этикетку (Swift)

import PdfOxide

let editor = try DocumentEditor.openFromBytes(labelTemplateBytes)
let pageCount = try editor.pageCount()

for page in 0..<pageCount {
    let qr = try BarcodeImage.generateQrCode("https://track.example.com/\(page)", sizePx: 128)
    try editor.addBarcodeToPage(page, qr, x: 420, y: 700, width: 80, height: 80)
    qr.close()
}

let stamped = try editor.saveToBytes()
editor.close()

Флаг функции

Функция barcodes подтягивает две дополнительные зависимости:

• barcoders — кодирование одномерных штрихкодов
• qrcode — кодирование QR-кодов

Без этого флага функции все методы штрихкодов возвращают ошибку, указывающую, что функция обязательна.

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

Часто задаваемые вопросы

В: В документации упоминаются generate_qr и generate_code — это правильные имена? О: Нет. Каноничные публичные имена методов — generate_qr_code и generate_barcode (опираются на C ABI pdf_generate_qr_code / pdf_generate_barcode). Внутри Rust низкоуровневые вспомогательные методы у BarcodeGenerator — это generate_qr и generate_1d; они являются внутренними помощниками Rust, а не межъязыковым интерфейсом.

В: Можно ли генерировать нативные штрихкоды из Python или Node? О: Python предоставляет generate_qr_svg и generate_barcode_svg, которые возвращают строки SVG, пригодные для встраивания или растеризации. Для дескрипторов PNG и размещения на странице на месте используйте привязки Swift, Go или C#, либо вызывайте C ABI напрямую. Нативные одношаговые конструкторы PDF (from_qrcode / from_barcode) доступны только в Rust.

В: Как разместить штрихкод в конкретной позиции существующего PDF? О: Сгенерируйте дескриптор изображения (generate_qr_code / generate_barcode), затем вызовите add_barcode_to_page(document, page_index, barcode, x, y, width, height). Координаты и размер задаются в точках пользовательского пространства PDF, а индекс страницы начинается с 0. В Swift это обёрнуто как DocumentEditor.addBarcodeToPage; из C/C++ вызывайте pdf_add_barcode_to_page.

В: Насколько быстра генерация? О: Писатель pdf_oxide построен на том же движке, который извлекает текст со средним временем 0,8 мс и 100% долей успешных прохождений на тестовом корпусе, поэтому кодирование QR- или одномерного штрихкода и вывод страницы фактически мгновенны для пакетных нагрузок.

Связанные страницы

• Текучий API PdfBuilder — настройка размера страницы и метаданных для PDF со штрихкодами
• Создание из изображений — встраивание PNG штрихкодов в PDF с несколькими видами содержимого
• Графика, узоры и градиенты — низкоуровневое рисование для пользовательских макетов этикеток
• Типы и перечисления — подробности о перечислении BarcodeType