QR Codes e Códigos de Barras

Gere QR codes e códigos de barras 1D diretamente como documentos PDF, como imagens PNG/SVG independentes, ou posicione-os em páginas de um PDF existente. A geração de códigos de barras fica atrás de uma flag de funcionalidade para manter a biblioteca principal enxuta.

Cobertura das bindings. Existem duas superfícies distintas de códigos de barras:

1. Construtores de PDF de uma só chamada (Pdf::from_qrcode / Pdf::from_barcode) e o BarcodeGenerator de baixo nível — expostos apenas em Rust.
2. A família de handles de imagem de código de barras (generate_qr_code, generate_barcode, add_barcode_to_page), apoiada nas funções da C ABI pdf_generate_qr_code / pdf_generate_barcode / pdf_add_barcode_to_page — exposta em Swift, Go e C#, e chamável diretamente a partir de C/C++ via FFI.
3. Geradores de SVG (generate_qr_svg / generate_barcode_svg) — expostos em Python e Rust.

Cada método abaixo está rotulado com as linguagens que realmente o expõem. Não presuma que um método existe em uma binding onde ele não é mostrado.

Requer a flag de funcionalidade: barcodes

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

Como gerar um QR code como PDF?

O caminho mais rápido em Rust é o construtor de uma só chamada Pdf::from_qrcode. O pdf_oxide grava o QR code em um PDF de página única que você pode salvar diretamente.

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

Como gerar uma imagem de código de barras (PNG/SVG) em vez de um PDF?

Quando você quer o glifo codificado como imagem — para embutir em um documento existente, enviar para um frontend web ou imprimir em uma etiqueta — use a família de handles de imagem ou os geradores de SVG. Estes são os nomes canônicos dos métodos: generate_qr_code e generate_barcode (os nomes antigos generate_qr / generate_code não fazem parte da superfície 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 — apenas 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)

Como adicionar um código de barras a uma página de um PDF existente?

Use add_barcode_to_page para posicionar uma imagem de código de barras gerada em uma página (baseada em 0) de um DocumentEditor, em uma dada posição e tamanho, e então salvar. Isso é exposto de forma idiomática em Swift como DocumentEditor.addBarcodeToPage e diretamente pela C ABI como pdf_add_barcode_to_page. A família de handles de imagem da qual ele depende não está encapsulada nas classes de editor de Go/C#, então use Swift (ou chame a C ABI a partir de C/C++) para o posicionamento no local.

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

Assinaturas dos métodos

Construtores de PDF de uma só chamada — apenas 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>

Família de handles de imagem de código de barras — Swift / Go / C# / C ABI

Linguagem	Gerador de QR	Gerador 1D	Posicionar na 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)	— (não encapsulado no editor)
C#	Barcode.GenerateQrCode(string data, int errorCorrection = 1, int sizePx = 300)	Barcode.Generate(string data, BarcodeFormat format = Code128, int sizePx = 300)	— (não encapsulado no 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)

Uma vez que você tenha um handle de código de barras, pode ler sua carga útil e renderizá-lo:

Operação	Swift	Go	C#	C ABI
Bytes PNG	imagePng(sizePx:)	PNGData()	ToPng(sizePx)	pdf_barcode_get_image_png
String SVG	svg(sizePx:)	SVGData()	ToSvg()	pdf_barcode_get_svg
Dados decodificados	data()	SourceData()	Data	pdf_barcode_get_data
Código do formato	format()	—	Format	pdf_barcode_get_format
Liberar handle	close()	Close()	Dispose()	pdf_barcode_free

Geradores 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: referência completa da API

Geração de QR code

Pdf::from_qrcode(data) — QR code padrão

Cria um PDF de página única com um QR code 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) — QR code personalizado

Controle total sobre tamanho, correção de erros, cores e zona de silêncio.

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 — configuração do QR

Método	Padrão	Descrição
.size(px)	200	Tamanho do QR code em pixels
.error_correction(level)	Medium	Nível de correção de erros
.quiet_zone(modules)	4	Largura da borda em módulos
.foreground(r, g, b, a)	Black (0,0,0,255)	Cor dos módulos (RGBA)
.background(r, g, b, a)	White (255,255,255,255)	Cor de fundo (RGBA)

Enum QrErrorCorrection

Variante	Capacidade de recuperação	Caso de uso	Inteiro (FFI)
Low	~7%	Densidade máxima de dados	0
Medium	~15%	Uso geral (padrão)	1
Quartile	~25%	Etiquetas que podem se danificar	2
High	~30%	Industrial / ambientes severos	3

Geração de códigos de barras 1D

Pdf::from_barcode(barcode_type, data) — código de barras padrão

Cria um PDF de página única com um código de barras usando o tamanho padrão (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

Controle total sobre as dimensões e cores do 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 — configuração 1D

Método	Padrão	Descrição
.width(px)	200	Largura do código de barras em pixels
.height(px)	80	Altura do código de barras em pixels
.foreground(r, g, b, a)	Black (0,0,0,255)	Cor das barras (RGBA)
.background(r, g, b, a)	White (255,255,255,255)	Cor de fundo (RGBA)
.show_text(bool)	false	Exibir texto legível por humanos

Enum BarcodeType

Variante	Nome	Formato dos dados	Inteiro (FFI)
Code128	Code 128	Alfanumérico (seleciona A/B/C automaticamente)	0
Code39	Code 39	Alfanumérico maiúsculo + 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 (quantidade par de dígitos)	5
Code93	Code 93	Alfanumérico (compacto)	6
Codabar	Codabar	Dígitos + caracteres especiais (início/fim A-D)	7

A C ABI pdf_generate_barcode e os wrappers de Go/Swift/C# selecionam a simbologia pela coluna Inteiro (FFI) acima. O enum BarcodeFormat do C# atualmente expõe Code128–Itf (0–5).

BarcodeGenerator de baixo nível — apenas Rust

Para gerar imagens de código de barras sem criar um PDF completo (por exemplo, para embutir em um 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)?;

Usando PdfBuilder com códigos de barras — apenas Rust

O PdfBuilder fornece uma interface fluente para definir o tamanho da página e os metadados do documento antes de gerar PDFs de código 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")?;

Exemplos avançados

Etiqueta de envio com vários 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.

Gerar etiquetas de produtos em lote (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 em lote (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)

Carimbar QR codes de rastreamento em todas as etiquetas (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 funcionalidade

A funcionalidade barcodes puxa duas dependências adicionais:

• barcoders — codificação de códigos de barras 1D
• qrcode — codificação de QR codes

Sem a flag de funcionalidade, todos os métodos de código de barras retornam um erro indicando que a funcionalidade é necessária.

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

Perguntas frequentes

P: A documentação menciona generate_qr e generate_code — esses são os nomes corretos? R: Não. Os nomes canônicos dos métodos públicos são generate_qr_code e generate_barcode (apoiados pela C ABI pdf_generate_qr_code / pdf_generate_barcode). Dentro de Rust, os auxiliares de baixo nível no BarcodeGenerator são generate_qr e generate_1d; esses são auxiliares internos de Rust, não a superfície compartilhada entre bindings.

P: Posso gerar códigos de barras nativos a partir de Python ou Node? R: O Python expõe generate_qr_svg e generate_barcode_svg, que retornam strings SVG que você pode embutir ou rasterizar. Para handles PNG e posicionamento no local na página, use as bindings de Swift, Go ou C#, ou chame a C ABI diretamente. Os construtores de PDF nativos de uma só chamada (from_qrcode / from_barcode) são exclusivos de Rust.

P: Como posiciono um código de barras em uma posição específica de um PDF existente? R: Gere o handle de imagem (generate_qr_code / generate_barcode) e então chame add_barcode_to_page(document, page_index, barcode, x, y, width, height). As coordenadas e o tamanho são em pontos do espaço do usuário do PDF e o índice da página é baseado em 0. Isso é encapsulado em Swift como DocumentEditor.addBarcodeToPage; a partir de C/C++, chame pdf_add_barcode_to_page.

P: Quão rápida é a geração? R: O writer do pdf_oxide é construído sobre o mesmo mecanismo que extrai texto com uma média de 0,8ms e taxa de aprovação de 100% no corpus de benchmark, então codificar um QR ou código de barras 1D e emitir uma página é praticamente instantâneo para cargas de trabalho em lote.

Páginas relacionadas

• API Fluente do PdfBuilder — Configure o tamanho da página e os metadados para PDFs de código de barras
• Criar a partir de Imagens — Embuta PNGs de código de barras em PDFs com múltiplos conteúdos
• Gráficos, Padrões e Sombreamentos — Desenho de baixo nível para layouts de etiquetas personalizados
• Tipos e Enums — Detalhes do enum BarcodeType