Skip to content
PDF Oxide

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- чи одновимірного штрихкоду й виведення сторінки фактично миттєве для пакетних навантажень.

Пов’язані сторінки