Ustaw tryby kodowania kodu QR w Pythonie

Każdy generator QR domyślnie wybiera tryb kodowania, a w większości przypadków to ustawienie jest wystarczające. Przestaje być wystarczające w momencie, gdy potrzebujesz nad nim kontroli — numeryczny identyfikator obok kodu produktu, blok japońskiego tekstu, którego nie chcesz przechowywać jako UTF‑8, lub ładunek, w którym potrzebujesz tych samych bajtów przy każdym generowaniu. Ten przewodnik pokazuje, jak ustawić tryby kodowania QR w Pythonie explicite, używając Aspose.BarCode for Python via .NET, tak aby pojedynczy symbol QR mógł zawierać segment numeryczny, segment alfanumeryczny, segment bajtowy i segment Kanji — każdy przechowywany w trybie, który najlepiej mu odpowiada.

Aspose.BarCode nazywa je trybami kompresji w swoich własnych nazwach API (QrExtCompactionMode), a specyfikacja QR określa je jako tryby kodowania. Są to te same cztery tryby pod dwiema nazwami, a w tym przewodniku używamy terminu “tryb kodowania” w całym dokumencie, ponieważ jest to określenie używane w specyfikacji i w większości bibliotek QR w Pythonie.

Dlaczego tryby kodowania QR wpływają na rozmiar symbolu i niezawodność skanowania

Rozmiar fizyczny kodu QR zależy od liczby bitów potrzebnych do jego ładunku, a liczba bitów na znak zależy całkowicie od trybu kodowania użytego dla tego segmentu. Specyfikacja definiuje cztery tryby danych o wyraźnie różnej gęstości:

Identyfikator 30‑cyfrowy kosztuje w przybliżeniu 100 bitów w trybie numerycznym i 240 bitów w trybie bajtowym. Ta różnica jest często wystarczająca, aby podnieść symbol o kilka wersji QR, a wyższa wersja oznacza więcej modułów w tym samym obszarze wydruku — mniejsze moduły i niższą skuteczność odczytu przy kamerach o niskiej rozdzielczości, zakrzywionych opakowaniach i zużytych etykietach.

Automatyczny wybór trybu radzi sobie dobrze z większością ładunków. Staje się ograniczający, gdy znasz strukturę swoich danych, a analizator nie: długi ciąg liczbowy przerwany pojedynczą literą, japoński tekst, dla którego tryb bajtowy zużywałby trzy bajty UTF‑8 na znak, lub identyfikator o stałym formacie, w którym chcesz deterministyczny wynik we wszystkich wersjach biblioteki.

Kiedy ręczne ustawianie trybu ma sens

Przełączanie trybów nie jest darmowe. Każde graniczne segmentu zapisuje czterobitowy wskaźnik trybu plus pole liczby znaków od ośmiu do szesnastu bitów, w zależności od wersji QR. Nadmierne segmentowanie ładunku może spowodować większy symbol niż pozostawienie decyzji generatorowi.

Ustawienie trybu jawnie opłaca się, gdy:

• Ładunek zawiera długie, jednorodne ciągi — 40‑cyfrowy numer seryjny, akapit kanji.
• Kodujesz tekst japoński i chcesz tryb Kanji z 13 bitami na znak zamiast trybu bajtowego z 24.
• Potrzebujesz powtarzalnego, identycznego bajtowo wyniku dla testów regresyjnych lub weryfikacji sumy kontrolnej.

Zazwyczaj nie warto dodatkowej złożoności przy krótkich ładunkach, danych, które zmieniają typ co kilka znaków, lub adresach URL, które automatyczna analiza już dobrze obsługuje. Podrozdział pomiaru poniżej pokazuje, jak sprawdzić, w którym przypadku się znajdujesz.

Dwa sposoby ustawiania trybów kodowania QR w Pythonie

Aspose.BarCode oferuje dwie ścieżki do tego samego zakodowanego wyniku i warto wiedzieć, dlaczego obie istnieją, zanim zaczniemy pisać kod.

Builder jest lepszym domyślnym wyborem. QrExtCompactionMode.NUMERIC albo istnieje, albo natychmiast podnosi AttributeError, podczas gdy błędnie wpisane \numm w łańcuchu cicho staje się danymi ładunku i pojawia się dopiero, gdy ktoś zeskanuje etykietę. Oba podejścia używają tego samego ustawienia generatora QREncodeMode.EXTENDED, więc możesz przełączać się między nimi bez zmiany czegokolwiek w dalszej części.

Ustaw tryby kodowania QR w Pythonie: krok po kroku

1. Instalacja i przygotowanie środowiska programistycznego

Aspose.BarCode for Python via .NET to biblioteka wieloplatformowa obsługująca generowanie, rozpoznawanie i manipulację ponad 50 symbolami, w tym QR. Zainstaluj z PyPI:

pip install aspose-barcode-for-python-via-net

Potwierdź wersję, ponieważ te interfejsy API wymagają wersji 26.6 lub nowszej:

pip show aspose-barcode

Następnie zweryfikuj, czy import się udaje. Pakiet wiąże się z środowiskiem uruchomieniowym .NET, więc udany import mówi więcej niż sama obecność plików na dysku:

from aspose.barcode.generation import QREncodeMode, QrExtCompactionMode

print("Aspose.BarCode imported successfully.")
print("EXTENDED mode available:", hasattr(QREncodeMode, "EXTENDED"))
print("Encoding modes:", [m for m in dir(QrExtCompactionMode) if m.isupper()])

Output:

Aspose.BarCode imported successfully.
EXTENDED mode available: True
Encoding modes: ['ALPHA_NUMERIC', 'AUTO', 'BYTES', 'KANJI', 'NUMERIC']

Jeśli brakuje EXTENDED, używasz wersji starszej niż 26.6 i musisz zaktualizować przed kontynuacją.

Jeśli masz plik licencji, zastosuj go raz przy uruchamianiu aplikacji, przed jakimkolwiek wywołaniem generacji lub rozpoznawania:

from aspose.barcode import License

license = License()
license.set_license("Aspose.BarCode.Python.NET.lic")

2. Ustaw tryb kodowania dla każdego segmentu za pomocą QrExtCodetextBuilder

QrExtCodetextBuilder przechowuje uporządkowaną listę segmentów. Każde wywołanie dołącza dane wraz z trybem kodowania, w którym powinny być przechowywane, a get_extended_codetext() składa je w ciąg w formacie rozszerzonym, który rozumie generator.

1. Importuj klasy generacji.
2. Utwórz QrExtCodetextBuilder.
3. Dodaj segment numeryczny przy użyciu QrExtCompactionMode.NUMERIC.
4. Dodaj segment alfanumeryczny przy użyciu QrExtCompactionMode.ALPHA_NUMERIC.
5. Dodaj segment bajtowy przy użyciu QrExtCompactionMode.BYTES.
6. Dodaj segment Kanji przy użyciu QrExtCompactionMode.KANJI.
7. Pobierz połączony rozszerzony kod tekstowy.

from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType
from aspose.barcode.generation import (
    BarcodeGenerator,
    EncodeTypes,
    QREncodeMode,
    QrExtCodetextBuilder,
    QrExtCompactionMode,
)

# Instantiate the Builder.
text_builder = QrExtCodetextBuilder()

# Numeric Segment — 3 Digits per 10 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.NUMERIC, "1234567"
)

# Alphanumeric Segment — Uppercase and Digits Only, 2 Characters per 11 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026"
)

# Byte Segment — Lowercase Forces Byte Mode, 8 Bits per Character.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.BYTES, "aspose2026"
)

# Kanji Segment — Shift-JIS Double-Byte Characters, 13 Bits Each.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.KANJI,
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A",
)

# Assemble the Final Extended Codetext.
codetext = text_builder.get_extended_codetext()
print("Extended codetext:", repr(codetext))

Wyjaśnienie

• Każde wywołanie add_codetext_with_compaction_mode ustawia tryb kodowania dla jednego segmentu. Kolejność ma znaczenie — dekoder zwraca segmenty połączone w kolejności, w jakiej zostały dodane.
• Zestaw alfanumeryczny jest celowo wąski: cyfry, wielkie litery A‑Z, spacja oraz $%*+-./:. Dlatego ASPOSE2026 pasuje do trybu alfanumerycznego, a aspose2026 nie. Małe litery nie należą do tego zestawu, więc taki segment musi używać trybu BYTES. Przekazywanie małych liter do ALPHA_NUMERIC jest najczęściej popełnianym błędem przy ustawianiu trybów w ten sposób.
• Segment Kanji używa znaków od \u3062, które są hiraganą, a nie właściwymi kanji. Tryb Kanji obejmuje dwubajtowy zakres Shift‑JIS, który zawiera kana, więc te znaki są kodowane przy użyciu 13 bitów każdy, zamiast 24 bitów, które tryb bajtowy zużyłby na każdy z nich w UTF‑8.
• get_extended_codetext() generuje ciąg znaków, który generator analizuje w trybie EXTENDED. Wydrukowanie go przy użyciu repr() warto zrobić raz — pokazuje składnię selektora emitowaną przez builder, co dokładnie jest zapisane ręcznie w następnym podrozdziale.

3. Ustaw tryb kodowania w linii, bez użycia Buildera

Gdy kod tekstowy pochodzi spoza Twojego kodu w Pythonie, możesz ustawić tryb każdego segmentu bezpośrednio za pomocą selektora. Każdy znacznik poprzedzony odwrotnym ukośnikiem kontroluje każdy znak aż do pojawienia się kolejnego znacznika:

# Equivalent to the Builder Output Above, Written Directly.
codetext = (
    r"\num1234567"
    r"\alnumASPOSE2026"
    r"\byteaspose2026"
    "\\kanji\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

Zwróć uwagę na ucieczki. W normalnym łańcuchu Pythona, "\num" nie jest selektorem — jest to znak nowej linii, po którym następuje um. Surowe łańcuchy (r"...") unikają tego problemu, ale surowy łańcuch również blokuje sekwencje ucieczki \u, co jest powodem, dla którego linia Kanji powyżej używa zwykłego łańcucha z \\kanji. Ta pułapka związana z ucieczkami jest praktycznym argumentem za preferowaniem buildera w sekcji 2.

4. Wygeneruj kod QR w trybie EXTENDED

Ustawianie trybów per‑segment nie ma efektu, dopóki generator nie zostanie poinstruowany, aby je odczytał. Bez QREncodeMode.EXTENDED informacje o segmencie są ignorowane, a znaczniki selektora są kodowane jako dosłowny tekst ładunku.

1. Utwórz BarcodeGenerator z EncodeTypes.QR i rozszerzonym kodem tekstowym.
2. Ustaw encode_mode na QREncodeMode.EXTENDED.
3. Skonfiguruj rozdzielczość oraz opcjonalnie poziom korekcji błędów i margines.
4. Zapisz kod kreskowy jako bezstratny PNG.

# Create the QR Generator with the Extended Codetext.
gen = BarcodeGenerator(EncodeTypes.QR, codetext)

# Switch to EXTENDED Mode So the Per-Segment Modes Are Respected.
gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED

# Render at Print Resolution Rather Than Upscaling Later.
gen.parameters.resolution = 300

# Save the Generated QR Code.
gen.save("extended_qr.png")

print("QR code generated and saved as extended_qr.png")

Wyjaśnienie

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED to linia, która aktywuje parsowanie segmentów. Pomiń ją, a generator utworzy prawidłowy, skanowalny kod QR zawierający dosłowny tekst \num1234567... — dlatego w następnym podrozdziale weryfikujemy, a nie zakładamy.
• gen.parameters.resolution = 300 renderuje w rozdzielczości druku. Symbole przeznaczone do drukarek etykiet lub grafiki opakowań powinny być generowane w ostatecznym rozmiarze, a nie skalowane później, co zmiękcza krawędzie modułów.
• save zapisuje bezstratny PNG. Unikaj JPEG dla dowolnej symbologii 2D — jego artefakty kompresji rozmywają siatkę modułów, którą odczytuje dekoder.

5. Sprawdź, czy tryb kodowania został zastosowany

Udane wygenerowanie nie dowodzi niczego na temat tego, czy tryby per‑segment zostały zastosowane. Krok dekodowania jest tym, co oddziela prawidłowo zakodowany symbol od tego, który niesie znaczniki selektora jako dane.

1. Zainicjuj BarCodeReader z ścieżką do pliku i DecodeType.QR.
2. Umaterializuj wyniki, aby niepowodzenie odczytu było widoczne.
3. Porównaj zdekodowany tekst z oczekiwanym połączeniem.

EXPECTED = (
    "1234567"
    "ASPOSE2026"
    "aspose2026"
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

# Initialise the QR Code Reader.
reader = BarCodeReader("extended_qr.png", DecodeType.QR)
results = list(reader.read_bar_codes())

if not results:
    raise ValueError("No QR code was detected in extended_qr.png.")

for result in results:
    decoded = result.code_text
    print("BarCode CodeText:", decoded)

if "\\num" in decoded or "\\alnum" in decoded:
        print("Selectors were encoded literally — check that encode_mode is EXTENDED.")
    elif decoded == EXPECTED:
        print("Verified: all four segments decoded and concatenated as expected.")
    else:
        print("Mismatch. Expected:", EXPECTED)

Wyjaśnienie

• DecodeType.QR ogranicza rozpoznawanie do symboli QR, co jest szybsze niż skanowanie każdej obsługiwanej symboliki i zapobiega dekodowaniu nieprawidłowego symbolu jako czegoś innego.
• list(...) wyraźnie określa przypadek niepowodzenia. Niepowodzenie rozpoznania zwraca pusty iterowalny zamiast podnosić wyjątek, więc niechroniona pętla for nad nieudaną próbą odczytu kończy się cicho i jest traktowana jako sukces.
• Sprawdzanie dosłownego \num łapie najczęstszy błąd w tym przepływie pracy: prawidłowe ustawienie segmentów i zapomnienie o ustawieniu encode_mode.
• Zdekodowane ładunki to surowe segmenty połączone razem, przy czym cała informacja o trybach została zużyta podczas kodowania. Tryby kodowania są instrukcjami dla kodera, a nie częścią danych.

6. Zmierz, czy ręczne ustawienie trybu pomogło

Ustawienie trybu kodowania ręcznie jest optymalizacją, więc należy to zmierzyć, a nie zakładać. Wygeneruj ten sam ładunek w obu wariantach i porównaj:

RAW = "1234567ASPOSE2026aspose2026"

# Automatic Mode Selection.
auto = BarcodeGenerator(EncodeTypes.QR, RAW)
auto.save("qr_auto.png")

# Manually Set Modes per Segment.
builder = QrExtCodetextBuilder()
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.NUMERIC, "1234567")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.BYTES, "aspose2026")

manual = BarcodeGenerator(EncodeTypes.QR, builder.get_extended_codetext())
manual.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED
manual.save("qr_manual.png")

print("Compare qr_auto.png and qr_manual.png — count modules along one edge.")

Policz moduły wzdłuż jednego brzegu każdego obrazu. Symbol QR wersji n ma 17 + 4n modułów po bokach, więc wersja 2 to 25×25, a wersja 3 to 29×29. Jeśli oba przypadki trafiają na tę samą wersję, automatyczna analiza już znalazła optymalną segmentację, a ręczne ustawianie trybu było obciążeniem konserwacyjnym bez korzyści. Odkrycie tego przed wysyłką jest użytecznym wynikiem, a nie zmarnowanym krokiem.

Uzyskaj darmową licencję

Aspose oferuje tymczasową darmową licencję, która znosi ograniczenia wersji ewaluacyjnej i odblokowuje pełną funkcjonalność do testów. Zamów ją ze strony tymczasowej licencji Aspose i zastosuj przed wywołaniem jakiejkolwiek generacji lub rozpoznawania.

Darmowe dodatkowe zasoby

• Dokumentacja produktu
• Referencja API
• Darmowe aplikacje kodów kreskowych online

Wnioski

Ustawianie trybów kodowania kodów QR w Pythonie sprowadza się do dwóch pytań: który segment otrzymuje który tryb oraz jak poinformować generator, aby szanował ten wybór. QrExtCodetextBuilder i QrExtCompactionMode odpowiadają na pierwsze pytanie w kodzie aplikacji; QREncodeMode.EXTENDED odpowiada na drugie w generatorze. Ten przewodnik obejmuje zarówno API buildera, jak i składnię selektora inline, którą generuje, tworząc czterosegmentowy symbol QR, weryfikując zdekodowane dane oraz mierząc różnicę rozmiaru w porównaniu z trybem automatycznym.

Preferuj builder w kodzie aplikacji — wykrywa błędy trybu w miejscu wywołania, a nie w skanerze. I zachowaj krok pomiarowy. Ustawianie trybu ręcznie to prawdziwa korzyść przy długich jednorodnych ładunkach i strata przy krótkich mieszanych, gdzie narzut przełączania trybu przewyższa oszczędności. Wygeneruj oba, porównaj liczbę modułów i pozwól wynikowi zdecydować, który kod utrzymujesz.

FAQs

1. Czym jest tryb kodowania QR i dlaczego miałbym go używać? Tryb kodowania informuje generator QR, jak traktować segment danych — numeryczny, alfanumeryczny, bajtowy lub Kanji. Każdy tryb ma inną gęstość danych, więc wybór odpowiedniego dla każdego segmentu utrzymuje wersję QR, a tym samym symbol, jak najmniejszy. Aspose.BarCode nazywa je trybami kompresji; specyfikacja QR określa je jako tryby kodowania.

2. Jakie tryby kodowania obsługuje QrExtCompactionMode? QrExtCompactionMode zapewnia NUMERIC, ALPHA_NUMERIC, BYTES i KANJI, odpowiadając czterem trybom danych QR zdefiniowanym w ISO/IEC 18004.

3. Czy powinienem używać QrExtCodetextBuilder czy selektorów inline EXTENDED do ustawiania trybu? Użyj buildera w kodzie aplikacji. Jest sprawdzany pod kątem typów, unika błędów związanych z ucieczką znaków backslash i składa rozszerzony kod tekstowy za Ciebie. Selektory inline są przydatne, gdy kod tekstowy pochodzi z konfiguracji, bazy danych lub innego systemu, który nie może wywołać buildera.

4. Jak tryb kodowania EXTENDED różni się od standardowego trybu kodowania QR? Tryb EXTENDED powoduje, że generator odczytuje kod jako serię predefiniowanych segmentów, z których każdy ma własny tryb kodowania, zamiast automatycznego wykrywania trybu na całym ciągu.

5. Czy mogę ustawić różne tryby kodowania dla różnych części jednego kodu QR? Tak. Dodaj kilka segmentów do QrExtCodetextBuilder, każdy z innym QrExtCompactionMode, a konstruktor wygeneruje pojedynczy rozszerzony kod tekstowy obejmujący wszystkie.

6. Czy kod QR wygenerowany przy użyciu mieszanych trybów kodowania jest kompatybilny ze standardowymi czytnikami? Tak. Kodowanie wielosegmentowe jest częścią specyfikacji QR, więc każdy zgodny skaner prawidłowo dekoduje ładunek i zwraca połączone dane.

7. Czy ręczne ustawienie trybu kodowania zawsze powoduje mniejszy kod QR? Nie. Każda granica segmentu kosztuje wskaźnik trybu i pole liczby znaków, więc podzielenie danych na wiele krótkich segmentów może spowodować, że symbol będzie większy. Ręczny wybór trybu opłaca się przy długich, jednorodnych ciągach danych numerycznych lub Kanji.

8. Czy potrzebuję licencji, aby ustawić tryby kodowania QR przy użyciu QrExtCodetextBuilder?
   Możesz ocenić API bez licencji, z zastrzeżeniem ograniczeń oceny. Darmowa tymczasowa licencja ze strony Aspose znosi te ograniczenia podczas testów, a użycie produkcyjne wymaga pełnej licencji.

9. Jaka wersja Aspose.BarCode for python-net obsługuje te API? QrExtCodetextBuilder, QrExtCompactionMode i QREncodeMode.EXTENDED są dostępne w Aspose.BarCode for Python via .NET 26.6 i późniejszych.

Czytaj więcej

• Generuj kod kreskowy MaxiCode w Pythonie
• Zbuduj generator kodu kreskowego Code 93 w Pythonie
• Generuj kod kreskowy i kod QR z logo w Pythonie