Atur Mode Pengkodean QR Code di Python

Setiap generator QR secara otomatis memilih mode enkoding untuk Anda secara default, dan kebanyakan waktu default tersebut sudah cukup. Hal ini tidak lagi memadai ketika Anda memerlukan kontrol atasnya — misalnya ID numerik di samping kode produk, blok teks Jepang yang tidak ingin disimpan sebagai UTF-8, atau payload di mana Anda memerlukan byte yang sama setiap kali menghasilkan kode. Panduan ini menunjukkan cara mengatur mode enkoding kode QR di Python secara eksplisit, menggunakan Aspose.BarCode for Python via .NET, sehingga satu simbol QR dapat membawa segmen numerik, segmen alfanumerik, segmen byte, dan segmen Kanji — masing‑masing disimpan dalam mode yang paling cocok.

Aspose.BarCode menyebut ini sebagai compaction modes dalam nama API‑nya (QrExtCompactionMode) dan spesifikasi QR sendiri menyebutnya encoding modes. Kedua istilah tersebut merujuk pada empat mode yang sama dengan dua nama, dan panduan ini menggunakan “encoding mode” di seluruhnya karena itu adalah istilah yang digunakan oleh spesifikasi dan sebagian besar perpustakaan QR Python.

Mengapa Mode Pengodean QR Mempengaruhi Ukuran Simbol dan Keandalan Pemindaian

Ukuran fisik kode QR ditentukan oleh berapa banyak bit yang dibutuhkan oleh muatannya, dan bit per karakter sepenuhnya bergantung pada mode enkoding yang digunakan untuk segmen tersebut. Spesifikasi mendefinisikan empat mode data dengan kepadatan yang sangat berbeda:

Pengidentifikasi 30 digit memerlukan sekitar 100 bit dalam mode numerik dan 240 bit dalam mode byte. Selisih itu sering cukup untuk menaikkan simbol ke beberapa versi QR, dan versi yang lebih tinggi berarti lebih banyak modul dalam area cetak yang sama — modul yang lebih kecil, serta tingkat pembacaan yang lebih rendah pada kamera beresolusi rendah, kemasan melengkung, dan label yang aus.

Pemilihan mode otomatis menangani sebagian besar payload dengan baik. Ini menjadi terbatas ketika Anda mengetahui bentuk data Anda dan analis tidak: rangkaian numerik panjang yang terputus oleh satu huruf, teks Jepang yang mode byte akan menghabiskan tiga byte UTF-8 per karakter, atau pengidentifikasi format tetap di mana Anda menginginkan output deterministik di seluruh versi perpustakaan.

Saat Menyetel Mode Secara Manual Layak Dilakukan

Peralihan mode tidak gratis. Setiap batas segmen menulis indikator mode empat‑bit ditambah bidang hitung karakter delapan hingga enam belas bit tergantung pada versi QR. Melebihi segmentasi payload dapat menghasilkan simbol yang lebih besar dibanding membiarkan generator yang memutuskan.

Menetapkan mode secara eksplisit memberikan manfaat ketika:

• Payload berisi rangkaian panjang yang homogen — sebuah serial 40 digit, sebuah paragraf Kanji.
• Anda sedang mengkodekan teks Jepang dan menginginkan mode Kanji pada 13 bit per karakter daripada mode byte pada 24.
• Anda memerlukan output yang dapat direproduksi dan identik byte‑nya untuk pengujian regresi atau validasi checksum.

Biasanya tidak sepadan dengan kompleksitas tambahan untuk payload pendek, data yang berganti tipe setiap beberapa karakter, atau URL, yang sudah ditangani dengan baik oleh analisis otomatis. Subbagian pengukuran di bawah ini menunjukkan cara memeriksa kasus mana yang Anda alami.

Dua Cara untuk Mengatur Mode Pengkodean QR di Python

Aspose.BarCode menawarkan dua jalur ke hasil terenkode yang sama, dan penting untuk mengetahui mengapa keduanya ada sebelum menulis kode.

Builder adalah default yang lebih baik. QrExtCompactionMode.NUMERIC ada atau langsung melempar AttributeError, sedangkan \numm yang salah ketik dalam string secara diam‑diam menjadi data payload dan hanya muncul ketika seseorang memindai label. Kedua pendekatan memberikan pengaturan generator yang sama QREncodeMode.EXTENDED, sehingga Anda dapat beralih di antara keduanya tanpa mengubah apa pun di hilir.

Mengatur Mode Pengkodean QR Code di Python: Langkah demi Langkah

1. Instal dan Siapkan Lingkungan Pengembangan

Aspose.BarCode for Python via .NET adalah perpustakaan lintas platform yang mendukung pembuatan, pengenalan, dan manipulasi lebih dari 50 simbol, termasuk QR. Instal dari PyPI:

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

Konfirmasi versi, karena API ini memerlukan 26.6 atau lebih baru:

pip show aspose-barcode

Kemudian verifikasi bahwa impor berhasil. Paket terikat ke runtime .NET, sehingga impor yang berhasil memberi Anda lebih banyak informasi daripada sekadar keberadaan file di disk:

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

Jika EXTENDED tidak ada, Anda berada pada rilis yang lebih lama dari 26.6 dan perlu memperbarui sebelum melanjutkan.

Jika Anda memiliki file lisensi, terapkan sekali saat aplikasi dimulai, sebelum panggilan generasi atau pengenalan apa pun:

from aspose.barcode import License

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

2. Atur Mode Pengkodean untuk Setiap Segmen dengan QrExtCodetextBuilder

QrExtCodetextBuilder menyimpan daftar terurut dari segmen. Setiap pemanggilan menambahkan data bersama dengan mode enkoding yang harus menyimpannya, dan get_extended_codetext() menyusunnya menjadi string format‑extended yang dipahami oleh generator.

1. Impor kelas generasi.
2. Buat sebuah QrExtCodetextBuilder.
3. Tambahkan segmen numerik dengan QrExtCompactionMode.NUMERIC.
4. Tambahkan segmen alfanumerik dengan QrExtCompactionMode.ALPHA_NUMERIC.
5. Tambahkan segmen byte dengan QrExtCompactionMode.BYTES.
6. Tambahkan segmen Kanji dengan QrExtCompactionMode.KANJI.
7. Ambil kode teks ekstended yang digabungkan.

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

Penjelasan

• Setiap add_codetext_with_compaction_mode call menetapkan mode pengkodean untuk satu segmen. Urutan penting — decoder mengembalikan segmen yang digabungkan dalam urutan Anda menambahkannya.
• Set alfanumerik sengaja sempit: digit, huruf besar A‑Z, spasi, dan $%*+-./:. Inilah mengapa ASPOSE2026 cocok dengan mode alfanumerik tetapi aspose2026 tidak. Huruf kecil berada di luar set, sehingga segmen itu harus menggunakan BYTES. Mengirim huruf kecil ke ALPHA_NUMERIC adalah kesalahan paling umum saat mengatur mode dengan cara ini.
• Segmen Kanji menggunakan \u3062 ke atas, yang merupakan hiragana bukan kanji sebenarnya. Mode Kanji mencakup rentang double‑byte Shift‑JIS, yang termasuk kana, sehingga ini dikodekan dengan 13 bit masing‑masing alih‑alih 24 bit yang akan digunakan mode byte untuk masing‑masing sebagai UTF‑8.
• get_extended_codetext() menghasilkan string yang diparsir generator dalam mode EXTENDED. Mencetaknya dengan repr() layak dilakukan sekali — itu menunjukkan sintaks selector yang dihasilkan builder, yang persis apa yang ditulis secara manual pada subbagian berikutnya.

3. Atur Mode Pengkodean Secara Inline, Tanpa Builder

Ketika teks kode berasal dari luar kode Python Anda, Anda dapat mengatur mode setiap segmen secara langsung dengan selector. Setiap penanda yang diawali dengan backslash mengatur setiap karakter hingga penanda berikutnya muncul:

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

Catat escaping. Dalam string Python normal, "\num" bukan selector — itu adalah newline diikuti oleh um. String mentah (r"...") menghindari masalah tersebut, tetapi string mentah juga memblokir escape \u, yang menjadi alasan mengapa baris Kanji di atas menggunakan string konvensional dengan \\kanji sebagai gantinya. Perangkap escaping ini menjadi argumen praktis untuk lebih memilih builder pada bagian 2.

4. Hasilkan QR Barcode dalam Mode EXTENDED

Pengaturan mode per‑segmen tidak berpengaruh sampai generator diberi tahu untuk membacanya. Tanpa QREncodeMode.EXTENDED, informasi segmen diabaikan dan penanda selector dienkode sebagai teks payload literal.

1. Buat sebuah BarcodeGenerator dengan EncodeTypes.QR dan teks kode yang diperluas.
2. Atur encode_mode ke QREncodeMode.EXTENDED.
3. Konfigurasikan resolusi, dan secara opsional tingkat koreksi kesalahan serta margin.
4. Simpan barcode ke PNG lossless.

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

Penjelasan

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED adalah baris yang mengaktifkan parsing segmen. Biarkan baris ini tidak ada dan generator menghasilkan kode QR yang valid dan dapat dipindai yang berisi teks literal \num1234567... — itulah mengapa subbagian berikutnya memverifikasi daripada mengasumsikan.
• gen.parameters.resolution = 300 merender pada resolusi cetak. Simbol yang ditujukan untuk printer label atau karya seni kemasan harus dihasilkan pada ukuran akhir, bukan diperbesar setelahnya, yang dapat melunakkan tepi modul.
• save menulis PNG tanpa kehilangan kualitas. Hindari JPEG untuk semua simbol 2D — artefak kompresinya mengaburkan kisi modul yang di‑sample oleh decoder.

5. Verifikasi Mode Pengkodean Telah Diterapkan

Generasi yang berhasil tidak membuktikan apa-apa tentang apakah mode per‑segmen telah diterapkan. Langkah decode adalah yang memisahkan simbol yang terkode dengan benar dari yang membawa penanda selector sebagai data.

1. Inisialisasi sebuah BarCodeReader dengan jalur file dan DecodeType.QR.
2. Materialisasikan hasilnya sehingga pembacaan yang gagal dapat terlihat.
3. Bandingkan teks yang didekode dengan penggabungan yang diharapkan.

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)

Penjelasan

• DecodeType.QR membatasi pengenalan hanya pada simbol QR, yang lebih cepat daripada memindai setiap simbol yang didukung dan mencegah simbol yang rusak di-decode sebagai sesuatu yang lain.
• list(...) membuat kasus kegagalan menjadi eksplisit. Kegagalan pengenalan mengembalikan iterable kosong alih-alih melempar pengecualian, sehingga loop for yang tidak dilindungi atas pembacaan yang gagal selesai secara diam-diam dan dianggap berhasil.
• Memeriksa literal \num menangkap kesalahan paling umum dalam alur kerja ini: mengatur segmen dengan benar dan lupa mengatur encode_mode.
• Payload yang didekode adalah segmen mentah yang digabungkan, dengan semua informasi mode dikonsumsi selama proses encoding. Mode encoding adalah instruksi untuk encoder, bukan bagian dari data.

6. Ukur Apakah Mengatur Mode Secara Manual Membantu

Mengatur mode enkoding secara manual adalah sebuah optimasi, jadi ukurlah daripada mengasumsikannya. Hasilkan payload yang sama dengan kedua cara dan bandingkan:

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

Hitung modul di sepanjang satu sisi setiap gambar. Sebuah simbol QR versi n memiliki ukuran 17 + 4n modul persegi, sehingga versi 2 berukuran 25×25 dan versi 3 berukuran 29×29. Jika keduanya berada pada versi yang sama, analisis otomatis sudah menemukan segmentasi optimal dan mengatur mode secara manual menjadi beban pemeliharaan tanpa manfaat. Menemukan hal itu sebelum pengiriman merupakan hasil yang berguna, bukan langkah yang terbuang.

Dapatkan Lisensi Gratis

Aspose menawarkan lisensi gratis sementara yang menghapus pembatasan evaluasi dan membuka semua fungsi penuh untuk pengujian. Minta satu dari halaman lisensi sementara Aspose dan terapkan sebelum panggilan generasi atau pengenalan apa pun.

Sumber Daya Tambahan Gratis

• Dokumentasi Produk
• Referensi API
• Aplikasi Barcode Online Gratis

Kesimpulan

Menetapkan mode enkoding kode QR di Python berhubungan dengan dua pertanyaan: segmen mana yang mendapatkan mode apa, dan bagaimana Anda memberi tahu generator untuk menghormati pilihan tersebut. QrExtCodetextBuilder dan QrExtCompactionMode menjawab pertanyaan pertama dalam kode aplikasi; QREncodeMode.EXTENDED menjawab pertanyaan kedua pada generator. Panduan ini mencakup kedua API builder dan sintaks pemilih inline yang dihasilkannya, menghasilkan simbol QR dengan empat segmen, memverifikasi muatan yang didekode, dan mengukur perbedaan ukuran dibandingkan mode otomatis.

Lebih pilih builder untuk kode aplikasi — ia menangkap kesalahan mode di lokasi pemanggilan alih‑alih di pemindai. Dan pertahankan langkah pengukuran. Menetapkan mode secara manual merupakan keuntungan nyata pada payload homogen yang panjang dan kerugian bersih pada yang pendek dan campuran di mana overhead pergantian mode melebihi penghematan. Hasilkan keduanya, bandingkan jumlah modul, dan biarkan hasilnya menentukan kode mana yang Anda pertahankan.

FAQs

1. Apa itu mode enkoding QR code dan mengapa saya harus menggunakannya?
   Sebuah mode enkoding memberi tahu generator QR bagaimana memperlakukan segmen data — numerik, alfanumerik, byte, atau Kanji. Setiap mode memiliki kepadatan data yang berbeda, sehingga memilih yang tepat per segmen menjaga versi QR, dan oleh karena itu simbolnya, tetap sekecil mungkin. Aspose.BarCode menyebut ini sebagai mode kompaksi; spesifikasi QR menyebutnya sebagai mode enkoding.

2. Mode pengkodean apa yang didukung oleh QrExtCompactionMode? QrExtCompactionMode menyediakan NUMERIC, ALPHA_NUMERIC, BYTES, dan KANJI, yang cocok dengan empat mode data QR yang didefinisikan dalam ISO/IEC 18004.

3. Haruskah saya menggunakan QrExtCodetextBuilder atau selector EXTENDED inline untuk mengatur mode? Gunakan builder untuk kode aplikasi. Builder ini diperiksa tipe, menghindari kesalahan pelolosan backslash, dan menyusun extended codetext untuk Anda. Selector inline berguna ketika codetext datang dari konfigurasi, basis data, atau sistem lain yang tidak dapat memanggil builder.

4. Bagaimana mode encode EXTENDED berbeda dari mode encode QR standar? Mode EXTENDED membuat generator membaca teks kode sebagai serangkaian segmen yang telah ditentukan sebelumnya, masing-masing dengan mode encodingnya sendiri, alih-alih menjalankan deteksi mode otomatis pada seluruh string.

5. Apakah saya dapat mengatur mode pengkodean yang berbeda untuk bagian yang berbeda dari satu kode QR? Ya. Tambahkan beberapa segmen ke QrExtCodetextBuilder, masing-masing dengan QrExtCompactionMode yang berbeda, dan pembangun menghasilkan satu codetext ekstended yang mencakup semuanya.

6. Apakah kode QR yang dihasilkan dengan mode pengkodean campuran kompatibel dengan pembaca standar?
   Ya. Pengkodean multi‑segmen merupakan bagian dari spesifikasi QR, sehingga pemindai yang mematuhi standar akan mendekode payload dengan benar dan mengembalikan data yang digabungkan.

7. Apakah mengatur mode pengkodean secara manual selalu menghasilkan kode QR yang lebih kecil? Tidak. Setiap batas segmen memerlukan indikator mode dan bidang hitung karakter, sehingga membagi data menjadi banyak segmen pendek dapat membuat simbol menjadi lebih besar. Pemilihan mode manual menguntungkan pada urutan panjang data numerik atau Kanji yang homogen.

8. Apakah saya memerlukan lisensi untuk mengatur mode enkoding QR dengan QrExtCodetextBuilder? Anda dapat mengevaluasi API tanpa lisensi, dengan batasan evaluasi. Lisensi sementara gratis dari situs web Aspose menghapus batasan tersebut selama pengujian, dan penggunaan produksi memerlukan lisensi penuh.

9. Versi berapa dari Aspose.BarCode for python-net yang mendukung API ini? QrExtCodetextBuilder, QrExtCompactionMode, dan QREncodeMode.EXTENDED tersedia di Aspose.BarCode for Python via .NET 26.6 dan yang lebih baru.

Baca Selengkapnya

• Hasilkan Barcode MaxiCode di Python
• Buat Generator Barcode Code 93 di Python
• Hasilkan Barcode dan QR Code dengan Logo di Python