Códigos QR y códigos de barras

Genera códigos QR y códigos de barras 1D directamente como documentos PDF, como imágenes PNG/SVG independientes, o colócalos en páginas de un PDF existente. La generación de códigos de barras está detrás de un flag de característica para mantener la biblioteca principal ligera.

Cobertura de los bindings. Existen dos superficies de códigos de barras distintas:

1. Constructores de PDF de una sola llamada (Pdf::from_qrcode / Pdf::from_barcode) y el BarcodeGenerator de bajo nivel: expuestos solo en Rust.
2. La familia de handles de imagen de código de barras (generate_qr_code, generate_barcode, add_barcode_to_page), respaldada por las funciones de la C ABI pdf_generate_qr_code / pdf_generate_barcode / pdf_add_barcode_to_page: expuesta en Swift, Go y C#, y llamable directamente desde C/C++ a través de FFI.
3. Generadores de SVG (generate_qr_svg / generate_barcode_svg): expuestos en Python y Rust.

Cada método de abajo está etiquetado con los lenguajes que realmente lo exponen. No supongas que un método existe en un binding donde no se muestra.

Requiere el flag de característica: barcodes

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

¿Cómo genero un código QR como PDF?

El camino más rápido en Rust es el constructor de una sola llamada Pdf::from_qrcode. pdf_oxide escribe el código QR en un PDF de una sola página que puedes guardar directamente.

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(())
}

¿Cómo genero una imagen de código de barras (PNG/SVG) en lugar de un PDF?

Cuando quieres el glifo codificado como imagen —para incrustarlo en un documento existente, enviarlo a un frontend web o imprimirlo en una etiqueta— usa la familia de handles de imagen o los generadores de SVG. Estos son los nombres canónicos de los métodos: generate_qr_code y generate_barcode (los nombres antiguos generate_qr / generate_code no forman parte de la superficie pública).

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 — solo 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)

¿Cómo añado un código de barras a una página de un PDF existente?

Usa add_barcode_to_page para colocar una imagen de código de barras generada en una página (con índice base 0) de un DocumentEditor, en una posición y un tamaño dados, y luego guarda. Esto se expone de forma idiomática en Swift como DocumentEditor.addBarcodeToPage y directamente a través de la C ABI como pdf_add_barcode_to_page. La familia de handles de imagen de la que depende no está envuelta en las clases de editor de Go/C#, así que usa Swift (o llama a la C ABI desde C/C++) para la colocación in situ.

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

Firmas de los métodos

Constructores de PDF de una sola llamada — solo 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>

Familia de handles de imagen de código de barras — Swift / Go / C# / C ABI

Lenguaje	Generador de QR	Generador 1D	Colocar en la página
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)	— (no envuelto en el editor)
C#	Barcode.GenerateQrCode(string data, int errorCorrection = 1, int sizePx = 300)	Barcode.Generate(string data, BarcodeFormat format = Code128, int sizePx = 300)	— (no envuelto en el editor)
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)

Una vez que tengas un handle de código de barras, puedes leer su carga útil y renderizarlo:

Operación	Swift	Go	C#	C ABI
Bytes PNG	imagePng(sizePx:)	PNGData()	ToPng(sizePx)	pdf_barcode_get_image_png
Cadena SVG	svg(sizePx:)	SVGData()	ToSvg()	pdf_barcode_get_svg
Datos decodificados	data()	SourceData()	Data	pdf_barcode_get_data
Código de formato	format()	—	Format	pdf_barcode_get_format
Liberar el handle	close()	Close()	Dispose()	pdf_barcode_free

Generadores de 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: referencia completa de la API

Generación de códigos QR

Pdf::from_qrcode(data) — código QR por defecto

Crea un PDF de una sola página con un código QR de 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) — código QR personalizado

Control total sobre el tamaño, la corrección de errores, los colores y la zona de silencio.

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 — configuración del QR

Método	Por defecto	Descripción
.size(px)	200	Tamaño del código QR en píxeles
.error_correction(level)	Medium	Nivel de corrección de errores
.quiet_zone(modules)	4	Ancho del borde en módulos
.foreground(r, g, b, a)	Black (0,0,0,255)	Color de los módulos (RGBA)
.background(r, g, b, a)	White (255,255,255,255)	Color de fondo (RGBA)

Enumeración QrErrorCorrection

Variante	Capacidad de recuperación	Caso de uso	Entero (FFI)
Low	~7 %	Máxima densidad de datos	0
Medium	~15 %	Uso general (por defecto)	1
Quartile	~25 %	Etiquetas que pueden dañarse	2
High	~30 %	Industrial / entornos hostiles	3

Generación de códigos de barras 1D

Pdf::from_barcode(barcode_type, data) — código de barras por defecto

Crea un PDF de una sola página con un código de barras usando el tamaño por defecto (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) — código de barras personalizado

Control total sobre las dimensiones y los colores del código de barras.

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 — configuración 1D

Método	Por defecto	Descripción
.width(px)	200	Ancho del código de barras en píxeles
.height(px)	80	Alto del código de barras en píxeles
.foreground(r, g, b, a)	Black (0,0,0,255)	Color de las barras (RGBA)
.background(r, g, b, a)	White (255,255,255,255)	Color de fondo (RGBA)
.show_text(bool)	false	Mostrar texto legible por humanos

Enumeración BarcodeType

Variante	Nombre	Formato de datos	Entero (FFI)
Code128	Code 128	Alfanumérico (selecciona A/B/C automáticamente)	0
Code39	Code 39	Alfanumérico en mayúsculas + símbolos	1
Ean13	EAN-13	13 dígitos (European Article Number)	2
Ean8	EAN-8	8 dígitos (EAN compacto)	3
UpcA	UPC-A	11-12 dígitos (Universal Product Code)	4
Itf	Interleaved 2 of 5	Pares numéricos (cantidad par de dígitos)	5
Code93	Code 93	Alfanumérico (compacto)	6
Codabar	Codabar	Dígitos + caracteres especiales (inicio/fin A-D)	7

La C ABI pdf_generate_barcode y los wrappers de Go/Swift/C# seleccionan la simbología mediante la columna Entero (FFI) anterior. La enumeración BarcodeFormat de C# expone actualmente Code128–Itf (0–5).

BarcodeGenerator de bajo nivel — solo Rust

Para generar imágenes de código de barras sin crear un PDF completo (por ejemplo, para incrustarlas en un documento existente):

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

Usar PdfBuilder con códigos de barras — solo Rust

PdfBuilder proporciona una interfaz fluida para establecer el tamaño de página y los metadatos del documento antes de generar PDFs de códigos de barras.

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

Ejemplos avanzados

Etiqueta de envío con varios códigos de barras (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.

Generar etiquetas de productos por lotes (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(' ', "_")))?;
}

SVGs de códigos de barras por lotes (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)

Estampar códigos QR de seguimiento en cada etiqueta (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()

Flag de característica

La característica barcodes arrastra dos dependencias adicionales:

• barcoders — codificación de códigos de barras 1D
• qrcode — codificación de códigos QR

Sin el flag de característica, todos los métodos de códigos de barras devuelven un error que indica que la característica es necesaria.

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

Preguntas frecuentes

P: La documentación menciona generate_qr y generate_code, ¿son esos los nombres correctos? R: No. Los nombres canónicos de los métodos públicos son generate_qr_code y generate_barcode (respaldados por la C ABI pdf_generate_qr_code / pdf_generate_barcode). Dentro de Rust, los auxiliares de bajo nivel de BarcodeGenerator son generate_qr y generate_1d; esos son auxiliares internos de Rust, no la superficie compartida entre bindings.

P: ¿Puedo generar códigos de barras nativos desde Python o Node? R: Python expone generate_qr_svg y generate_barcode_svg, que devuelven cadenas SVG que puedes incrustar o rasterizar. Para handles PNG y la colocación in situ en la página, usa los bindings de Swift, Go o C#, o llama a la C ABI directamente. Los constructores de PDF nativos de una sola llamada (from_qrcode / from_barcode) son exclusivos de Rust.

P: ¿Cómo coloco un código de barras en una posición específica de un PDF existente? R: Genera el handle de imagen (generate_qr_code / generate_barcode) y luego llama a add_barcode_to_page(document, page_index, barcode, x, y, width, height). Las coordenadas y el tamaño están en puntos del espacio de usuario del PDF y el índice de página tiene base 0. Esto se envuelve en Swift como DocumentEditor.addBarcodeToPage; desde C/C++ llama a pdf_add_barcode_to_page.

P: ¿Qué tan rápida es la generación? R: El escritor de pdf_oxide está construido sobre el mismo motor que extrae texto con una media de 0,8 ms y una tasa de éxito del 100 % en el corpus de referencia, así que codificar un QR o un código de barras 1D y emitir una página es prácticamente instantáneo para cargas de trabajo por lotes.

Páginas relacionadas

• API fluida de PdfBuilder — Configura el tamaño de página y los metadatos para PDFs de códigos de barras
• Crear a partir de imágenes — Incrusta PNGs de códigos de barras en PDFs con múltiples contenidos
• Gráficos, patrones y sombreados — Dibujo de bajo nivel para diseños de etiquetas personalizados
• Tipos y enumeraciones — Detalles de la enumeración BarcodeType