Generowanie kodów kreskowych

Potok generowania kodów kreskowych w Aspose.BarCode FOSS dla Python opiera się na architekturze trójstopniowej: parsowanie → kodowanie → renderowanie. Wysokopoziomowy API (generate() i per-symbology helpers) koordynuje te etapy poprzez BarcodeService.

Wysokopoziomowe generowanie API

Najprostszym sposobem generowania kodu kreskowego jest użycie funkcji pomocniczych per-symbology:

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

Każdy pomocnik zwraca obiekt Barcode. Wywołaj to_svg() dla wyjścia SVG lub to_png() dla wyjścia PNG.

Generyczna funkcja generate() przyjmuje jako argument ciąg znaków określający nazwę symbologii:

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

Prawidłowe nazwy symbologii: "code128", "code39", "ean13", "ean8", "qr", "upca", "upce".

BarcodeService

BarcodeService koordynuje trzy etapy potoku. Zawiera SymbologyRegistry i 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")

Metoda generate():

Wyszukuje SymbologyDefinition w rejestrze
Wywołuje InputParser.parse(), aby zweryfikować i znormalizować dane wejściowe
Wywołuje SymbologyEncoder.encode(), aby wygenerować EncodedSymbol
Zwraca Barcode otaczający symbol i jego profil

SymbologyRegistry

SymbologyRegistry przechowuje obiekty SymbologyDefinition kluczowane nazwami kanonicznymi i aliasami:

Metoda	Opis
`get_definition(name)`	Pobierz pełną definicję symbologii
`get_parser(name)`	Pobierz `InputParser` dla symbologii
`get_encoder(name)`	Pobierz `SymbologyEncoder` dla symboliki
`get_profile(name)`	Pobierz `SymbologyProfile` z domyślnymi wartościami
`get_text_policy(name)`	Pobierz `TextLayoutPolicy` do renderowania tekstu
`register(definition)`	Zarejestruj nowy `SymbologyDefinition`

EncoderRegistry jest aliasem wstecznie kompatybilnym dla SymbologyRegistry.

SymbologyDefinition

SymbologyDefinition łączy wszystkie komponenty potrzebne do obsługi jednej symbologii:

Właściwość	Typ	Opis
`name`	`str`	Kanoniczny identyfikator symboliki
`parser`	`InputParser`	Weryfikuje i normalizuje dane wejściowe
`encoder`	`SymbologyEncoder`	Koduje dane do macierzy modułowej
`profile`	`SymbologyProfile`	Domyślne wartości, możliwości i polityka tekstowa
`aliases`	`tuple[str, ...]`	Alternatywne nazwy do wyszukiwania

EncodedSymbol

Zwrócony przez enkoder EncodedSymbol zawiera:

matrix — ModuleMatrix z logiczną siatką modułów kodu kreskowego
metadata — SymbolMetadata z nazwą symbologii, tekstem wyświetlanym i szczegółami kodowania

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 zapewnia metodę get(x, y), która zwraca wartość modułu w określonej pozycji.

NormalizedPayload

NormalizedPayload jest pośrednią reprezentacją pomiędzy parsowaniem a kodowaniem:

Właściwość	Opis
`symbology`	Kanoniczna nazwa symboliki
`data`	Zweryfikowane dane wejściowe (`str` lub `bytes`)
`input_kind`	Jak wejście zostało sklasyfikowane
`code128_encode_mode`	Ustalono tryb Code 128 (jeśli dotyczy)
`code39_encode_mode`	Ustalono tryb Code 39 (jeśli dotyczy)
`qr_error_correction_level`	Ustalono korekcję błędów QR (jeśli dotyczy)
`qr_version`	Ustalono wersję QR (jeśli dotyczy)
`qr_encoding_mode`	Ustalono tryb kodowania QR (jeśli dotyczy)

OptionsResolver

OptionsResolver scala opcje renderowania dostarczone przez użytkownika z domyślnymi ustawieniami symboliki:

Metoda	Opis
`resolve(profile, options)`	Wygeneruj `ResolvedRenderOptions` poprzez połączenie opcji użytkownika z domyślnymi ustawieniami profilu
`merge_options(earlier, later)`	Połącz dwa `RenderOptions` (późniejsze wartości nadpisują)
`coerce_options(options)`	Znormalizuj surowe opcje do `RenderOptions`

Wskazówki i najlepsze praktyki

Używaj pomocników specyficznych dla symboliki (code128(), qr(), itp.) zamiast generate() dla bezpieczeństwa typów — zapewniają, że używana jest właściwa klasa opcji.
Właściwość Barcode.symbol zapewnia bezpośredni dostęp do EncodedSymbol w celu niestandardowego renderowania lub analizy.
BarcodeService jest bezstanowa — jedna instancja może generować kody kreskowe w wielu wątkach.
Przechwyć BarcodeError jako klasę bazową, aby obsłużyć wszystkie wyjątki związane z kodami kreskowymi w jednym bloku.

Typowe problemy

Problem	Przyczyna	Naprawa
`SymbologyNotFoundError`	Nazwa nie jest zarejestrowana w `SymbologyRegistry`	Sprawdź pisownię; użyj kanonicznych nazw
`InvalidInputError`	Dane naruszają wymagania dotyczące symboliki	Sprawdź zestaw znaków i wymagania dotyczące długości
Pusty wynik SVG	Brak zakodowanych modułów	Sprawdź, czy dane nie są puste i są prawidłowe dla symboliki

Zobacz także

Aspose.BarCode for Python — Enterprise Documentation