Generazione di codici a barre

Il flusso di generazione dei codici a barre in Aspose.BarCode FOSS per Python segue un’architettura a tre fasi: analizza → codifica → renderizza. L’API di alto livello (generate() e gli helper per simbologia) orchestra queste fasi attraverso BarcodeService.

Generazione di alto livello API

Il modo più semplice per generare un codice a barre è tramite le funzioni helper per simbologia:

import aspose_barcode_foss as barcode

bc_128 = barcode.code128("ABC123")
bc_qr = barcode.qr("https://example.com")
bc_ean = barcode.ean13("590123412345")
bc_upca = barcode.upca("01234567890")

Ogni helper restituisce un oggetto Barcode. Chiama to_svg() per l’output SVG o to_png() per l’output PNG.

La funzione generica generate() accetta una stringa con il nome della simbologia:

bc = barcode.generate("code128", "DATA")
svg = bc.to_svg()

Nomi di simbologia validi: "code128", "code39", "ean13", "ean8", "qr", "upca", "upce".

BarcodeService

BarcodeService coordina le tre fasi della pipeline. Contiene un SymbologyRegistry e un OptionsResolver:

from aspose_barcode_foss import BarcodeService

# The default service is used by all helper functions
# You can create a custom service for testing or extension:
service = BarcodeService(registry=registry, options_resolver=resolver)
result = service.generate("code128", "DATA")

Il metodo generate():

Cerca il SymbologyDefinition nel registro
Chiama il InputParser.parse() per validare e normalizzare l’input
Chiama il SymbologyEncoder.encode() per produrre un EncodedSymbol
Restituisce un Barcode che avvolge il simbolo e il suo profilo

SymbologyRegistry

SymbologyRegistry memorizza gli oggetti SymbologyDefinition indicizzati per nomi canonici e alias:

Metodo	Descrizione
`get_definition(name)`	Recupera una definizione completa della simbologia
`get_parser(name)`	Ottieni il `InputParser` per una simbologia
`get_encoder(name)`	Ottieni il `SymbologyEncoder` per una simbologia
`get_profile(name)`	Ottieni il `SymbologyProfile` con i valori predefiniti
`get_text_policy(name)`	Ottieni il `TextLayoutPolicy` per il rendering del testo
`register(definition)`	Registra un nuovo `SymbologyDefinition`

EncoderRegistry è un alias retrocompatibile di SymbologyRegistry.

SymbologyDefinition

Un SymbologyDefinition raggruppa tutti i componenti necessari a supportare una simbologia:

Proprietà	Tipo	Descrizione
`name`	`str`	Identificatore di simbologia canonica
`parser`	`InputParser`	Valida e normalizza i dati di input
`encoder`	`SymbologyEncoder`	Codifica i dati in una matrice di moduli
`profile`	`SymbologyProfile`	Impostazioni predefinite, capacità e policy del testo
`aliases`	`tuple[str, ...]`	Nomi alternativi per la ricerca

EncodedSymbol

Il EncodedSymbol restituito da un encoder contiene:

matrix — un ModuleMatrix con la griglia logica dei moduli del codice a barre
metadata — un SymbolMetadata con il nome della simbologia, il testo visualizzato e i dettagli di codifica

bc = barcode.code128("TEST")
symbol = bc.symbol

print(f"Matrix: {symbol.matrix.width}x{symbol.matrix.height}")
print(f"Display text: {symbol.metadata.display_text}")
print(f"Symbology: {symbol.metadata.symbology}")

ModuleMatrix fornisce un metodo get(x, y) che restituisce il valore del modulo in una data posizione.

NormalizedPayload

Il NormalizedPayload è la rappresentazione intermedia tra l’analisi e la codifica:

Proprietà	Descrizione
`symbology`	Nome della simbologia canonica
`data`	Dati di input convalidati (`str` o `bytes`)
`input_kind`	Come è stato classificato l’input
`code128_encode_mode`	Modalità Code 128 risolta (se applicabile)
`code39_encode_mode`	Modalità Code 39 risolta (se applicabile)
`qr_error_correction_level`	Correzione degli errori QR risolta (se applicabile)
`qr_version`	Versione QR risolta (se applicabile)
`qr_encoding_mode`	Modalità di codifica QR risolta (se applicabile)

OptionsResolver

OptionsResolver unisce le opzioni di rendering fornite dall’utente con i valori predefiniti della simbologia:

Metodo	Descrizione
`resolve(profile, options)`	Genera un `ResolvedRenderOptions` unendo le opzioni dell’utente con i valori predefiniti del profilo
`merge_options(earlier, later)`	Unisci due `RenderOptions` (i valori successivi sovrascrivono)
`coerce_options(options)`	Normalizza le opzioni grezze in `RenderOptions`

Suggerimenti e migliori pratiche

Utilizza gli helper per simbologia (code128(), qr(), ecc.) invece di generate() per la sicurezza dei tipi — garantiscono che venga utilizzata la classe di opzioni corretta.
La proprietà Barcode.symbol fornisce accesso diretto al EncodedSymbol per il rendering personalizzato o l’analisi.
BarcodeService è senza stato — un’istanza può generare codici a barre su più thread.
Cattura BarcodeError come classe base per gestire tutte le eccezioni relative ai codici a barre in un unico blocco.

Problemi comuni

Problema	Causa	Correzione
`SymbologyNotFoundError`	Nome non registrato in `SymbologyRegistry`	Controlla l’ortografia; usa i nomi canonici
`InvalidInputError`	I dati violano i requisiti di simbologia	Controlla il set di caratteri e i requisiti di lunghezza
Output SVG vuoto	Nessun modulo codificato	Verifica che i dati non siano vuoti e siano validi per la simbologia

Vedi anche

Aspose.BarCode for Python — Enterprise Documentation