QR-Code-Codierungsmodi in Python festlegen

Jeder QR‑Generator wählt standardmäßig einen Codierungsmodus für Sie aus, und die meiste Zeit ist diese Vorgabe in Ordnung. Sie hört auf, in Ordnung zu sein, sobald Sie die Kontrolle darüber benötigen — eine numerische ID neben einem Produktcode, ein Block japanischen Textes, den Sie nicht als UTF‑8 speichern möchten, oder eine Nutzlast, bei der Sie jedes Mal dieselben Bytes erhalten wollen, wenn Sie sie erzeugen. Dieser Leitfaden zeigt, wie man set QR code encoding modes in Python explizit festlegt, indem man Aspose.BarCode for Python via .NET verwendet, sodass ein einzelnes QR‑Symbol einen numerischen Abschnitt, einen alphanumerischen Abschnitt, einen Byte‑Abschnitt und einen Kanji‑Abschnitt tragen kann — jeder im Modus gespeichert, der am besten passt.

Aspose.BarCode nennt diese Komprimierungsmodi in seiner eigenen API‑Bezeichnung (QrExtCompactionMode) und die QR‑Spezifikation selbst nennt sie Kodierungsmodi. Es sind dieselben vier Modi unter zwei Namen, und dieser Leitfaden verwendet durchgehend den Begriff “Kodierungsmodus”, da dies der Begriff ist, den die Spezifikation und die meisten Python‑QR‑Bibliotheken verwenden.

Warum QR-Codierungsmodi die Symbolgröße und Scanzuverlässigkeit beeinflussen

Die physische Größe eines QR‑Codes wird durch die Anzahl der Bits bestimmt, die seine Nutzdaten benötigen, und die Bits pro Zeichen hängen vollständig vom für dieses Segment verwendeten Codierungsmodus ab. Die Spezifikation definiert vier Datenmodi mit deutlich unterschiedlichen Dichten:

Ein 30‑stelliger Bezeichner kostet ungefähr 100 Bit im numerischen Modus und 240 Bit im Byte‑Modus. Diese Lücke reicht oft aus, um das Symbol um mehrere QR‑Versionen nach oben zu schieben, und eine höhere Version bedeutet mehr Module im gleichen Druckbereich — kleinere Module und eine geringere Lesegeschwindigkeit bei Kameras mit niedriger Auflösung, gewölbter Verpackung und abgenutzten Etiketten.

Die automatische Modusauswahl verarbeitet die meisten Payloads gut. Sie wird jedoch einschränkend, wenn Sie die Form Ihrer Daten kennen und der Analyzer dies nicht tut: ein langer numerischer Lauf, der durch einen einzelnen Buchstaben unterbrochen wird, japanischer Text, für den der Byte‑Modus drei UTF‑8‑Bytes pro Zeichen benötigen würde, oder ein festes Format eines Identifikators, bei dem Sie über verschiedene Bibliotheksversionen hinweg deterministische Ausgaben wünschen.

Wenn das manuelle Festlegen des Modus sinnvoll ist

Der Moduswechsel ist nicht kostenlos. Jede Segmentgrenze schreibt einen vier‑Bit‑Modusindikator plus ein Zeichenanzahlfeld von acht bis sechzehn Bit, abhängig von der QR‑Version. Eine Übersegmentierung einer Nutzlast kann ein größeres Symbol erzeugen als das automatische Entscheiden des Generators.

Die explizite Einstellung des Modus lohnt sich, wenn:

• Der Payload enthält lange, homogene Sequenzen — eine 40‑stellige Seriennummer, einen Absatz mit Kanji.
• Sie codieren japanischen Text und möchten den Kanji‑Modus mit 13 Bit pro Zeichen statt des Byte‑Modus mit 24 Bit verwenden.
• Sie benötigen reproduzierbare, byte‑identische Ausgaben für Regressionstests oder die Validierung von Prüfsummen.

Es lohnt sich in der Regel nicht, die zusätzliche Komplexität für kurze Payloads, Daten, die alle paar Zeichen den Typ wechseln, oder URLs, die bereits von der automatischen Analyse gut gehandhabt werden, hinzuzufügen. Der Messabschnitt unten zeigt, wie Sie prüfen können, in welchem Fall Sie sich befinden.

Zwei Wege, um QR‑Codierungsmodi in Python festzulegen

Aspose.BarCode bietet zwei Wege zum gleichen codierten Ergebnis, und es lohnt sich zu wissen, warum beide existieren, bevor man Code schreibt.

Der Builder ist die bessere Vorgabe. QrExtCompactionMode.NUMERIC existiert entweder oder löst sofort einen AttributeError aus, während ein falsch geschriebener \numm in einem String stillschweigend zu Nutzdaten wird und erst sichtbar wird, wenn jemand das Etikett scannt. Beide Ansätze verwenden dieselbe Generator‑Einstellung QREncodeMode.EXTENDED, sodass Sie zwischen ihnen wechseln können, ohne etwas im nachgelagerten Prozess zu ändern.

QR-Code-Codierungsmodi in Python festlegen: Schritt für Schritt

1. Installation und Vorbereitung der Entwicklungsumgebung

Aspose.BarCode for Python via .NET ist eine plattformübergreifende Bibliothek, die die Erzeugung, Erkennung und Manipulation von mehr als 50 Symbolen, einschließlich QR, unterstützt. Installation von PyPI:

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

Bestätigen Sie die Version, da diese APIs Version 26.6 oder neuer benötigen:

pip show aspose-barcode

Überprüfen Sie anschließend, ob der Import aufgelöst wird. Das Paket bindet an eine .NET‑Laufzeit, sodass ein erfolgreicher Import mehr aussagt als nur das Vorhandensein von Dateien auf der Festplatte:

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']

Wenn EXTENDED fehlt, verwenden Sie eine Version, die älter als 26.6 ist, und müssen ein Upgrade durchführen, bevor Sie fortfahren.

Wenn Sie eine Lizenzdatei haben, wenden Sie sie einmal beim Anwendungsstart an, bevor ein Generierungs‑ oder Erkennungsaufruf erfolgt:

from aspose.barcode import License

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

2. Legen Sie den Codierungsmodus für jedes Segment mit QrExtCodetextBuilder fest

QrExtCodetextBuilder hält eine geordnete Liste von Segmenten. Jeder Aufruf fügt Daten zusammen mit dem Kodierungsmodus hinzu, in dem sie gespeichert werden sollen, und get_extended_codetext() setzt sie zu dem erweiterten Format‑String zusammen, den der Generator versteht.

1. Importieren Sie die Generierungsklassen.
2. Erstellen Sie einen QrExtCodetextBuilder.
3. Fügen Sie ein numerisches Segment mit QrExtCompactionMode.NUMERIC hinzu.
4. Fügen Sie ein alphanumerisches Segment mit QrExtCompactionMode.ALPHA_NUMERIC hinzu.
5. Fügen Sie ein Byte‑Segment mit QrExtCompactionMode.BYTES hinzu.
6. Fügen Sie ein Kanji‑Segment mit QrExtCompactionMode.KANJI hinzu.
7. Rufen Sie den kombinierten erweiterten Codetext ab.

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

Erklärung

• Jeder Aufruf von add_codetext_with_compaction_mode legt den Kodierungsmodus für ein Segment fest. Die Reihenfolge ist wichtig – der Decoder gibt die Segmente in der Reihenfolge zurück, in der Sie sie hinzugefügt haben.
• Der alphanumerische Zeichensatz ist bewusst eng: Ziffern, Großbuchstaben A‑Z, Leerzeichen und $%*+-./:. Deshalb passt ASPOSE2026 in den alphanumerischen Modus, aspose2026 jedoch nicht. Kleinbuchstaben liegen außerhalb des Zeichensatzes, sodass dieses Segment BYTES verwenden muss. Das Übergeben von Kleinbuchstaben an ALPHA_NUMERIC ist der häufigste Fehler bei der Einstellung der Modi auf diese Weise.
• Das Kanji‑Segment verwendet \u3062 und folgende Zeichen, die Hiragana und nicht echte Kanji sind. Der Kanji‑Modus deckt den Shift‑JIS‑Doppelbyte‑Bereich ab, der Kana enthält, sodass diese mit 13 Bit pro Zeichen kodiert werden, anstatt der 24 Bit, die der Byte‑Modus für jedes Zeichen in UTF‑8 benötigen würde.
• get_extended_codetext() erzeugt die Zeichenkette, die der Generator im EXTENDED‑Modus analysiert. Das Ausgeben mit repr() ist einmalig sinnvoll – es zeigt Ihnen die Selektorsyntax, die der Builder erzeugt, und genau das schreibt der nächste Unterabschnitt von Hand.

3. Kodierungsmodus inline festlegen, ohne den Builder

Wenn der Quelltext außerhalb Ihres Python‑Codes stammt, können Sie den Modus jedes Segments direkt mit einem Selektor festlegen. Jeder mit einem Backslash vorangestellte Marker steuert jedes Zeichen, bis der nächste Marker erscheint:

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

Beachten Sie das Escaping. In einem normalen Python‑String ist "\num" kein Selektor — es ist ein Zeilenumbruch, gefolgt von um. Rohstrings (r"...") umgehen das Problem, aber ein Rohstring blockiert auch \u‑Escapes, weshalb die Kanji‑Zeile oben einen konventionellen String mit \\kanji verwendet. Diese Escaping‑Falle ist das praktische Argument dafür, den Builder in Abschnitt 2 zu bevorzugen.

4. Generieren Sie den QR-Barcode im EXTENDED-Modus

Das Festlegen von per‑Segment‑Modi hat keine Wirkung, bis dem Generator mitgeteilt wird, dass er sie lesen soll. Ohne QREncodeMode.EXTENDED wird die Segmentinformation ignoriert und die Selektormarker werden als wörtlicher Payload‑Text codiert.

1. Erstellen Sie einen BarcodeGenerator mit EncodeTypes.QR und dem erweiterten Codetext.
2. Setzen Sie encode_mode auf QREncodeMode.EXTENDED.
3. Konfigurieren Sie die Auflösung und optional das Fehlerkorrektur‑Level sowie den Rand.
4. Speichern Sie den Barcode als verlustfreies 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")

Erklärung

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED ist die Zeile, die die Segmentanalyse aktiviert. Lassen Sie sie weg und der Generator erzeugt einen gültigen, scanbaren QR‑Code, der den wörtlichen Text \num1234567... enthält — weshalb der nächste Abschnitt verifiziert statt annimmt.
• gen.parameters.resolution = 300 rendert mit Druckauflösung. Symbole, die für Etikettendrucker oder Verpackungsdesigns bestimmt sind, sollten in der endgültigen Größe erzeugt werden, nicht nachträglich skaliert, da dies die Modulkanten weicher macht.
• save schreibt ein verlustfreies PNG. Vermeiden Sie JPEG für jede 2D‑Symbologie — seine Kompressionsartefakte verwischen das Modulgitter, das der Decoder abtastet.

5. Überprüfen, ob der Codierungsmodus angewendet wurde

Eine erfolgreiche Generierung beweist nichts darüber, ob die per‑Segment‑Modi wirksam wurden. Der Dekodierungsschritt ist das, was ein korrekt codiertes Symbol von einem unterscheidet, das Selektormarker als Daten trägt.

1. Initialisieren Sie einen BarCodeReader mit dem Dateipfad und DecodeType.QR.
2. Materialisieren Sie die Ergebnisse, damit ein fehlgeschlagener Lesevorgang sichtbar ist.
3. Vergleichen Sie den decodierten Text mit der erwarteten Verkettung.

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)

Erklärung

• DecodeType.QR beschränkt die Erkennung auf QR‑Symbole, was schneller ist, als jede unterstützte Symbolik zu scannen, und verhindert, dass ein fehlerhaftes Symbol fälschlich als etwas anderes dekodiert wird.
• list(...) macht den Fehlfall explizit. Ein Erkennungsfehler liefert ein leeres Iterable statt einer Ausnahme, sodass eine ungeschützte for‑Schleife über einen fehlgeschlagenen Lesevorgang still endet und als Erfolg gewertet wird.
• Das Prüfen auf ein wörtliches \num fängt den häufigsten Fehler in diesem Workflow ab: die Segmente korrekt zu setzen und dabei zu vergessen, encode_mode zu setzen.
• Die dekodierte Nutzlast ist die Rohsegmente, die aneinandergereiht wurden, wobei alle Modusinformationen während der Kodierung verbraucht wurden. Kodiermodi sind Anweisungen an den Encoder, nicht Teil der Daten.

6. Messen, ob das manuelle Einstellen des Modus geholfen hat

Das manuelle Festlegen des Kodierungsmodus ist eine Optimierung, daher sollte man ihn messen, anstatt davon auszugehen. Erzeugen Sie die gleiche Nutzlast auf beiden Arten und vergleichen Sie sie:

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

Zählen Sie die Module entlang einer Kante jedes Bildes. Ein QR‑Version n‑Symbol ist 17 + 4n Module quadratisch, sodass Version 2 25×25 und Version 3 29×29 groß ist. Wenn beide auf dieselbe Version fallen, hat die automatische Analyse bereits die optimale Segmentierung gefunden und das manuelle Einstellen des Modus war ein Wartungsaufwand ohne Nutzen. Das vor dem Versand zu entdecken, ist ein nützliches Ergebnis, kein verschwendeter Schritt.

Kostenlose Lizenz erhalten

Aspose bietet eine temporäre kostenlose Lizenz, die Evaluierungsbeschränkungen aufhebt und die volle Funktionalität für Tests freischaltet. Fordern Sie eine von der Aspose temporäre Lizenzseite an und wenden Sie sie vor jedem Generierungs‑ oder Erkennungsaufruf an.

Kostenlose zusätzliche Ressourcen

• Produktdokumentation
• API-Referenz
• Kostenlose Online-Barcode-Apps

Fazit

Das Festlegen von QR‑Code‑Codierungsmodi in Python lässt sich auf zwei Fragen reduzieren: Welches Segment erhält welchen Modus und wie teilt man dem Generator diese Wahl mit. QrExtCodetextBuilder und QrExtCompactionMode beantworten die erste Frage im Anwendungscode; QREncodeMode.EXTENDED beantwortet die zweite beim Generator. Dieser Leitfaden behandelte sowohl die Builder‑API als auch die von ihr erzeugte Inline‑Selektor‑Syntax, erzeugte ein QR‑Symbol mit vier Segmenten, überprüfte die dekodierte Nutzlast und maß den Größenunterschied gegenüber dem automatischen Modus.

Bevorzugen Sie den Builder für Anwendungscode — er fängt Modusfehler an der Aufrufstelle ab, anstatt beim Scanner. Und behalten Sie den Messschritt bei. Das manuelle Festlegen des Modus ist bei langen homogenen Payloads ein echter Gewinn und bei kurzen gemischten ein Nettoverlust, wenn der Overhead des Moduswechsels die Einsparungen übersteigt. Generieren Sie beide, vergleichen Sie die Modulzahlen und lassen Sie das Ergebnis entscheiden, welchen Code Sie beibehalten.

FAQs

1. Was ist ein QR-Code-Codierungsmodus und warum sollte ich einen verwenden? Ein Codierungsmodus teilt dem QR-Generator mit, wie ein Datenabschnitt zu behandeln ist — numerisch, alphanumerisch, Byte oder Kanji. Jeder Modus hat eine unterschiedliche Datendichte, sodass die Wahl des richtigen Modus pro Abschnitt die QR-Version und damit das Symbol so klein wie möglich hält. Aspose.BarCode nennt diese Kompaktierungsmodi; die QR-Spezifikation nennt sie Codierungsmodi.

2. Welche Codierungsmodi unterstützt QrExtCompactionMode? QrExtCompactionMode bietet NUMERIC, ALPHA_NUMERIC, BYTES und KANJI und entspricht den vier QR‑Datenmodi, die in ISO/IEC 18004 definiert sind.

3. Soll ich QrExtCodetextBuilder oder inline EXTENDED Selektoren verwenden, um den Modus festzulegen? Verwenden Sie den Builder für Anwendungscode. Er ist typüberprüft, vermeidet Backslash‑Escape‑Fehler und erstellt den erweiterten Codetext für Sie. Inline‑Selektoren sind nützlich, wenn der Codetext aus einer Konfiguration, einer Datenbank oder einem anderen System kommt, das den Builder nicht aufrufen kann.

4. Wie unterscheidet sich der EXTENDED‑Kodiermodus vom Standard‑QR‑Kodiermodus? Der EXTENDED‑Modus lässt den Generator den Codetext als eine Reihe vordefinierter Segmente lesen, von denen jedes seinen eigenen Kodiermodus hat, anstatt eine automatische Moduserkennung über die gesamte Zeichenkette durchzuführen.

5. Kann ich verschiedene Kodierungsmodi für verschiedene Teile eines QR-Codes festlegen? Ja. Fügen Sie mehrere Segmente zu QrExtCodetextBuilder hinzu, jedes mit einem anderen QrExtCompactionMode, und der Builder erzeugt einen einzigen erweiterten Codetext, der alle abdeckt.

6. Ist ein QR-Code, der mit gemischten Codierungsmodi erzeugt wurde, mit Standardlesern kompatibel? Ja. Die Mehrsegment‑Codierung ist Teil der QR‑Spezifikation, sodass jeder konforme Scanner die Nutzdaten korrekt dekodiert und die zusammengefügten Daten zurückgibt.

7. Führt das manuelle Festlegen des Kodierungsmodus immer zu einem kleineren QR-Code? Nein. Jede Segmentgrenze kostet einen Modusindikator und ein Zeichenanzahlfeld, sodass das Aufteilen von Daten in viele kurze Segmente das Symbol vergrößern kann. Die manuelle Modusauswahl lohnt sich bei langen, homogenen Abschnitten numerischer oder Kanji‑Daten.

8. Benötige ich eine Lizenz, um QR-Codierungsmodi mit QrExtCodetextBuilder festzulegen? Sie können die API ohne Lizenz evaluieren, vorbehaltlich der Evaluierungsbeschränkungen. Eine kostenlose temporäre Lizenz von der Aspose-Website hebt diese Beschränkungen während des Tests auf, und die Produktion erfordert eine Voll‑Lizenz.

9. Welche Version von Aspose.BarCode for python-net unterstützt diese APIs? QrExtCodetextBuilder, QrExtCompactionMode und QREncodeMode.EXTENDED sind in Aspose.BarCode for Python via .NET 26.6 und später verfügbar.

Weiterlesen

• MaxiCode-Barcode in Python generieren
• Code‑93‑Barcode‑Generator in Python erstellen
• Barcode und QR‑Code mit Logo in Python generieren