Imposta le modalità di codifica del codice QR in Python

Tutti i generatori QR scelgono una modalità di codifica per impostazione predefinita e nella maggior parte dei casi questa impostazione è adeguata. Non è più adeguata nel momento in cui hai bisogno di controllarla — un ID numerico accanto a un codice prodotto, un blocco di testo giapponese che non vuoi memorizzare come UTF‑8, o un payload in cui hai bisogno degli stessi byte ogni volta che lo generi. Questa guida mostra come impostare le modalità di codifica QR in Python esplicitamente, usando Aspose.BarCode for Python via .NET, in modo che un singolo simbolo QR possa contenere un segmento numerico, un segmento alfanumerico, un segmento byte e un segmento Kanji — ciascuno memorizzato nella modalità più adatta.

Aspose.BarCode chiama queste modalità di compattazione nei nomi della sua API (QrExtCompactionMode) e la specifica QR le chiama modalità di codifica. Sono le stesse quattro modalità con due nomi diversi, e questa guida utilizza “modalità di codifica” in tutto il testo poiché è il termine usato dalla specifica e dalla maggior parte delle librerie QR per Python.

Perché le modalità di codifica QR influenzano le dimensioni del simbolo e l’affidabilità della scansione

La dimensione fisica di un codice QR è determinata dal numero di bit necessari per il suo payload e i bit per carattere dipendono interamente dalla modalità di codifica utilizzata per quel segmento. La specifica definisce quattro modalità di dati con densità notevolmente diverse:

Un identificatore a 30 cifre richiede circa 100 bit in modalità numerica e 240 bit in modalità byte. Tale differenza è spesso sufficiente a far salire il simbolo di diverse versioni QR, e una versione più alta comporta più moduli nella stessa area stampata — moduli più piccoli e un tasso di lettura più basso su fotocamere a bassa risoluzione, confezioni curve e etichette usurate.

La selezione automatica della modalità gestisce bene la maggior parte dei payload. Diventa limitante quando conosci la forma dei tuoi dati e l’analizzatore no: una lunga sequenza numerica interrotta da una singola lettera, testo giapponese per il quale la modalità byte impiegherebbe tre byte UTF‑8 per carattere, o un identificatore a formato fisso in cui desideri un output deterministico tra le versioni della libreria.

Quando impostare la modalità manualmente ne vale la pena

Il cambio di modalità non è gratuito. Ogni confine di segmento scrive un indicatore di modalità a quattro bit più un campo di conteggio dei caratteri da otto a sedici bit a seconda della versione QR. Un’eccessiva segmentazione di un payload può produrre un simbolo più grande rispetto a lasciare che il generatore decida.

Impostare esplicitamente la modalità è vantaggioso quando:

• Il payload contiene sequenze lunghe e omogenee — un seriale a 40 cifre, un paragrafo di Kanji.
• Stai codificando testo giapponese e desideri la modalità Kanji a 13 bit per carattere anziché la modalità byte a 24.
• Hai bisogno di un output riproducibile e identico a livello di byte per test di regressione o per la convalida del checksum.

Di solito non vale la pena la complessità aggiuntiva per payload brevi, dati che alternano tipo ogni pochi caratteri o URL, che l’analisi automatica gestisce già bene. La sottosezione di misurazione qui sotto mostra come verificare in quale caso ti trovi.

Due modi per impostare le modalità di codifica QR in Python

Aspose.BarCode offre due percorsi allo stesso risultato codificato, ed è utile sapere perché entrambi esistono prima di scrivere il codice.

Il costruttore è il valore predefinito migliore. QrExtCompactionMode.NUMERIC o esiste o solleva immediatamente un AttributeError, mentre un \numm digitato in modo errato in una stringa diventa silenziosamente dati di payload e si manifesta solo quando qualcuno scansiona l’etichetta. Entrambi gli approcci forniscono la stessa impostazione del generatore QREncodeMode.EXTENDED, quindi è possibile passare da uno all’altro senza modificare nulla a valle.

Imposta le modalità di codifica QR Code in Python: Passo dopo passo

1. Installa e prepara l’ambiente di sviluppo

Aspose.BarCode for Python via .NET è una libreria cross‑platform che supporta la generazione, il riconoscimento e la manipolazione di oltre 50 simbologie, incluso QR. Installa da PyPI:

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

Conferma la versione, poiché queste API richiedono la 26.6 o successiva:

pip show aspose-barcode

Quindi verifica che l’importazione venga risolta. Il pacchetto si lega a un runtime .NET, quindi un’importazione riuscita ti dice più della semplice presenza dei file sul disco:

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

Se EXTENDED è mancante, stai usando una versione precedente alla 26.6 e devi eseguire l’aggiornamento prima di continuare.

Se disponi di un file di licenza, applicalo una sola volta all’avvio dell’applicazione, prima di qualsiasi chiamata di generazione o riconoscimento:

from aspose.barcode import License

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

2. Imposta la modalità di codifica per ogni segmento con QrExtCodetextBuilder

QrExtCodetextBuilder contiene un elenco ordinato di segmenti. Ogni chiamata aggiunge dati insieme alla modalità di codifica che dovrebbe memorizzarli e get_extended_codetext() li assembla nella stringa a formato esteso che il generatore comprende.

1. Importa le classi di generazione.
2. Crea un QrExtCodetextBuilder.
3. Aggiungi un segmento numerico con QrExtCompactionMode.NUMERIC.
4. Aggiungi un segmento alfanumerico con QrExtCompactionMode.ALPHA_NUMERIC.
5. Aggiungi un segmento di byte con QrExtCompactionMode.BYTES.
6. Aggiungi un segmento Kanji con QrExtCompactionMode.KANJI.
7. Recupera il codetext esteso combinato.

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

Spiegazione

• Ogni chiamata a add_codetext_with_compaction_mode imposta la modalità di codifica per un segmento. L’ordine è importante — il decodificatore restituisce i segmenti concatenati nella sequenza in cui li hai aggiunti.
• L’insieme alfanumerico è deliberatamente ristretto: cifre, lettere maiuscole A-Z, spazio e $%*+-./:. Per questo ASPOSE2026 è compatibile con la modalità alfanumerica, mentre aspose2026 no. Le lettere minuscole non fanno parte dell’insieme, quindi quel segmento deve utilizzare BYTES. Passare minuscole a ALPHA_NUMERIC è l’errore più comune quando si impostano le modalità in questo modo.
• Il segmento Kanji utilizza \u3062 e successivi, che sono hiragana piuttosto che kanji veri e propri. La modalità Kanji copre l’intervallo a doppio byte Shift-JIS, che include i kana, quindi questi vengono codificati a 13 bit ciascuno invece dei 24 bit che la modalità byte impiegherebbe per ciascuno in UTF‑8.
• get_extended_codetext() genera la stringa che il generatore analizza in modalità EXTENDED. Stampare la stringa con repr() vale la pena farlo una volta — mostra la sintassi del selettore che il builder emette, che è esattamente ciò che la sezione successiva scrive manualmente.

3. Imposta la modalità di codifica inline, senza il builder

Quando il testo del codice proviene da fuori del tuo codice Python, puoi impostare la modalità di ciascun segmento direttamente con un selettore. Ogni marcatore preceduto da backslash controlla ogni carattere fino a quando non appare il marcatore successivo:

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

Nota la gestione delle escape. In una normale stringa Python, "\num" non è un selettore — è un newline seguito da um. Le stringhe raw (r"...") evitano il problema, ma una stringa raw blocca anche le escape \u, motivo per cui la riga Kanji sopra utilizza una stringa convenzionale con \\kanji invece. Questa trappola di escape è l’argomento pratico per preferire il builder nella sezione 2.

4. Genera il codice QR in modalità ESTESA

Impostare le modalità per segmento non ha alcun effetto finché il generatore non viene istruito a leggerle. Senza QREncodeMode.EXTENDED, le informazioni sul segmento vengono ignorate e i marcatori di selezione vengono codificati come testo di payload letterale.

1. Crea un BarcodeGenerator con EncodeTypes.QR e il testo codificato esteso.
2. Imposta encode_mode su QREncodeMode.EXTENDED.
3. Configura la risoluzione e, facoltativamente, il livello di correzione degli errori e il margine.
4. Salva il codice a barre in un PNG senza perdita.

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

Spiegazione

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED è la riga che attiva l’analisi dei segmenti. Lasciandola fuori, il generatore produce un QR code valido e leggibile contenente il testo letterale \num1234567... — motivo per cui la sezione successiva verifica anziché presumere.
• gen.parameters.resolution = 300 rende a risoluzione di stampa. I simboli destinati a stampanti di etichette o a grafiche di imballaggio dovrebbero essere generati alla dimensione finale, non ridimensionati successivamente, poiché ciò smorza i bordi dei moduli.
• save scrive un PNG senza perdita. Evita JPEG per qualsiasi simbologia 2D — i suoi artefatti di compressione offuscano la griglia dei moduli che il decoder campiona.

5. Verifica che la modalità di codifica sia stata applicata

La generazione riuscita non dimostra nulla sul fatto che le modalità per segmento siano state applicate. Il passaggio di decodifica è ciò che separa un simbolo correttamente codificato da uno che trasporta marcatori di selettore come dati.

1. Inizializzare un BarCodeReader con il percorso del file e DecodeType.QR.
2. Materializzare i risultati in modo che una lettura fallita sia visibile.
3. Confrontare il testo decodificato con la concatenazione prevista.

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)

Spiegazione

• DecodeType.QR limita il riconoscimento ai simboli QR, il che è più veloce rispetto alla scansione di tutte le simbologie supportate e impedisce che un simbolo malformato venga decodificato come qualcos’altro.
• list(...) rende esplicito il caso di errore. Un fallimento di riconoscimento restituisce un iterabile vuoto anziché sollevare un’eccezione, quindi un ciclo for non protetto su una lettura fallita termina silenziosamente e viene interpretato come successo.
• Verificare un letterale \num intercetta l’errore più comune in questo flusso di lavoro: impostare correttamente i segmenti e dimenticare di impostare encode_mode.
• Il payload decodificato è la concatenazione dei segmenti grezzi, con tutte le informazioni di modalità consumate durante la codifica. Le modalità di codifica sono istruzioni per il codificatore, non fanno parte dei dati.

6. Misurare se l’impostazione manuale della modalità ha aiutato

Impostare manualmente la modalità di codifica è un’ottimizzazione, quindi misurala piuttosto che assumerla. Genera lo stesso payload in entrambi i modi e confrontali:

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

Conta i moduli lungo un lato di ogni immagine. Un simbolo QR versione n è un quadrato di 17 + 4n moduli, quindi la versione 2 è 25×25 e la versione 3 è 29×29. Se entrambi ricadono nella stessa versione, l’analisi automatica ha già trovato la segmentazione ottimale e impostare manualmente la modalità era un onere di manutenzione senza vantaggi. Scoprire ciò prima della spedizione è un risultato utile, non un passo sprecato.

Ottieni una licenza gratuita

Aspose offre una licenza temporanea gratuita che rimuove le restrizioni di valutazione e sblocca tutte le funzionalità per i test. Richiedine una dalla pagina della licenza temporanea di Aspose e applicala prima di qualsiasi chiamata di generazione o riconoscimento.

Risorse aggiuntive gratuite

• Documentazione del prodotto
• Riferimento API
• Applicazioni Barcode online gratuite

Conclusione

Impostare le modalità di codifica del codice QR in Python si riduce a due domande: quale segmento ottiene quale modalità e come si indica al generatore di rispettare tale scelta. QrExtCodetextBuilder e QrExtCompactionMode rispondono alla prima domanda nel codice dell’applicazione; QREncodeMode.EXTENDED risponde alla seconda nel generatore. Questa guida ha coperto sia l’API del builder sia la sintassi del selettore inline che produce, generando un simbolo QR a quattro segmenti, verificando il payload decodificato e misurando la differenza di dimensione rispetto alla modalità automatica.

Preferisci il builder per il codice dell’applicazione — cattura gli errori di modalità al punto di chiamata invece che allo scanner. E mantieni il passaggio di misurazione. Impostare manualmente la modalità è un vero vantaggio su payload lunghi e omogenei e una perdita netta su quelli brevi e misti, dove l’overhead del cambio di modalità supera i risparmi. Genera entrambi, confronta i conteggi dei moduli e lascia che il risultato decida quale codice mantenere.

FAQs

1. Che cos’è una modalità di codifica QR e perché dovrei usarla? Una modalità di codifica indica al generatore QR come trattare un segmento di dati — numerico, alfanumerico, byte o Kanji. Ogni modalità ha una densità di dati diversa, quindi scegliere quella giusta per segmento mantiene la versione QR, e quindi il simbolo, il più piccolo possibile. Aspose.BarCode chiama queste modalità di compattazione; la specifica QR le chiama modalità di codifica.

2. Quali modalità di codifica supporta QrExtCompactionMode? QrExtCompactionMode fornisce NUMERIC, ALPHA_NUMERIC, BYTES e KANJI, corrispondenti alle quattro modalità di dati QR definite in ISO/IEC 18004.

3. Devo usare QrExtCodetextBuilder o i selettori EXTENDED inline per impostare la modalità? Usa il builder per il codice dell’applicazione. È controllato dal tipo, evita errori di escape dei backslash e assembla il codetext esteso per te. I selettori inline sono utili quando il codetext proviene da configurazione, un database o un altro sistema che non può chiamare il builder.

4. In che modo la modalità di codifica EXTENDED differisce dalla modalità di codifica QR standard? La modalità EXTENDED fa sì che il generatore legga il testo del codice come una serie di segmenti predefiniti, ognuno con la propria modalità di codifica, invece di eseguire il rilevamento automatico della modalità su tutta la stringa.

5. Posso impostare modalità di codifica diverse per parti diverse di un unico QR code? Sì. Aggiungi diversi segmenti a QrExtCodetextBuilder, ognuno con un diverso QrExtCompactionMode, e il builder genera un unico codetext esteso che copre tutti.

6. Un codice QR generato con modalità di codifica miste è compatibile con i lettori standard? Sì. La codifica multi‑segmento fa parte della specifica QR, quindi qualsiasi scanner conforme decodifica correttamente il payload e restituisce i dati concatenati.

7. Impostare manualmente la modalità di codifica produce sempre un codice QR più piccolo? No. Ogni confine di segmento richiede un indicatore di modalità e un campo di conteggio dei caratteri, quindi suddividere i dati in molti segmenti brevi può rendere il simbolo più grande. La selezione manuale della modalità è vantaggiosa per lunghi tratti omogenei di dati numerici o Kanji.

8. Devo avere una licenza per impostare le modalità di codifica QR con QrExtCodetextBuilder?
   È possibile valutare l’API senza licenza, soggetto a restrizioni di valutazione. Una licenza temporanea gratuita dal sito web di Aspose rimuove tali restrizioni durante i test, e l’uso in produzione richiede una licenza completa.

9. Quale versione di Aspose.BarCode for python-net supporta queste API? QrExtCodetextBuilder, QrExtCompactionMode e QREncodeMode.EXTENDED sono disponibili in Aspose.BarCode for Python via .NET 26.6 e successive.

Leggi di più

• Genera codice a barre MaxiCode in Python
• Crea generatore di codice a barre Code 93 in Python
• Genera codice a barre e QR Code con logo in Python