Thiết lập các chế độ mã hoá QR Code trong Python

Mỗi trình tạo QR sẽ tự động chọn một chế độ mã hoá cho bạn theo mặc định, và hầu hết thời gian chế độ mặc định này là ổn. Nó sẽ không còn ổn nữa ngay khi bạn cần kiểm soát nó — một ID số bên cạnh mã sản phẩm, một khối văn bản tiếng Nhật mà bạn không muốn lưu dưới dạng UTF-8, hoặc một tải trọng mà bạn cần các byte giống hệt nhau mỗi khi tạo. Hướng dẫn này cho thấy cách set QR code encoding modes in Python một cách rõ ràng, sử dụng Aspose.BarCode for Python via .NET, để một ký hiệu QR duy nhất có thể chứa một đoạn số, một đoạn chữ và số, một đoạn byte, và một đoạn Kanji — mỗi đoạn được lưu trong chế độ phù hợp nhất.

Aspose.BarCode gọi chúng là compaction modes trong tên API riêng (QrExtCompactionMode) và bản đặc tả QR gọi chúng là encoding modes. Chúng là bốn chế độ giống nhau chỉ có hai tên, và hướng dẫn này sử dụng “encoding mode” xuyên suốt vì đó là thuật ngữ mà bản đặc tả và hầu hết các thư viện QR Python sử dụng.

Tại sao các chế độ mã hoá QR ảnh hưởng đến kích thước ký hiệu và độ tin cậy khi quét

Kích thước vật lý của mã QR được quyết định bởi số bit mà dữ liệu tải trọng của nó cần, và số bit trên mỗi ký tự phụ thuộc hoàn toàn vào chế độ mã hoá được sử dụng cho đoạn đó. Đặc tả định nghĩa bốn chế độ dữ liệu với mật độ khác nhau đáng kể:

Một định danh 30 chữ số tốn khoảng 100 bit ở chế độ số và 240 bit ở chế độ byte. Khoảng cách này thường đủ để đẩy ký hiệu lên một vài phiên bản QR, và một phiên bản cao hơn nghĩa là có nhiều mô-đun hơn trong cùng một khu vực in — các mô-đun nhỏ hơn, và tỷ lệ đọc thấp hơn trên các máy ảnh độ phân giải thấp, bao bì cong và nhãn mòn.

Chế độ lựa chọn tự động xử lý hầu hết các tải trọng tốt. Tuy nhiên, nó trở nên hạn chế khi bạn biết dạng dữ liệu của mình nhưng bộ phân tích không biết: một chuỗi số dài bị ngắt bởi một ký tự chữ, văn bản tiếng Nhật mà chế độ byte sẽ tốn ba byte UTF-8 cho mỗi ký tự, hoặc một định danh định dạng cố định mà bạn muốn đầu ra xác định được trên các phiên bản thư viện.

Khi việc thiết lập chế độ thủ công là đáng giá

Chuyển đổi chế độ không phải là miễn phí. Mỗi ranh giới đoạn ghi một chỉ báo chế độ bốn bit cộng với trường đếm ký tự từ tám đến mười sáu bit tùy thuộc vào phiên bản QR. Việc phân đoạn quá mức một tải có thể tạo ra một ký hiệu lớn hơn so với để trình tạo quyết định.

Việc đặt chế độ một cách rõ ràng sẽ có lợi khi:

• Payload chứa các chuỗi dài, đồng nhất — một số sê-ri 40 chữ số, một đoạn văn Kanji.
• Bạn đang mã hoá văn bản Nhật và muốn chế độ Kanji với 13 bit mỗi ký tự thay vì chế độ byte với 24 bit.
• Bạn cần đầu ra có thể tái tạo, byte‑identical cho các bài kiểm tra hồi quy hoặc xác thực checksum.

Thông thường, việc thêm độ phức tạp không đáng giá đối với các payload ngắn, dữ liệu thay đổi loại sau mỗi vài ký tự, hoặc các URL, mà phân tích tự động đã xử lý tốt. Phần phụ đo lường bên dưới cho thấy cách kiểm tra trường hợp bạn đang ở.

Hai cách để đặt chế độ mã hoá QR trong Python

Aspose.BarCode cung cấp hai cách để đạt được cùng một kết quả đã mã hoá, và việc hiểu lý do tại sao cả hai tồn tại trước khi viết mã là điều đáng biết.

Trình xây dựng là mặc định tốt hơn. QrExtCompactionMode.NUMERIC hoặc tồn tại hoặc ngay lập tức gây ra một AttributeError, trong khi một lỗi gõ nhầm \numm trong chuỗi sẽ im lặng trở thành dữ liệu tải trọng và chỉ xuất hiện khi ai đó quét nhãn. Cả hai cách tiếp cận đều cung cấp cùng một cài đặt bộ tạo QREncodeMode.EXTENDED, vì vậy bạn có thể chuyển đổi giữa chúng mà không thay đổi gì downstream.

Thiết lập các chế độ mã hoá QR Code trong Python: Từng bước

1. Cài đặt và chuẩn bị môi trường phát triển

Aspose.BarCode for Python via .NET là một thư viện đa nền tảng hỗ trợ tạo, nhận dạng và thao tác trên hơn 50 biểu tượng, bao gồm cả QR. Cài đặt từ PyPI:

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

Xác nhận phiên bản, vì các API này yêu cầu 26.6 trở lên:

pip show aspose-barcode

Sau đó, xác nhận việc nhập được giải quyết. Gói này liên kết với môi trường .NET, vì vậy một lần nhập thành công cho bạn biết nhiều hơn chỉ sự hiện diện của các tệp trên đĩa:

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

Nếu EXTENDED bị thiếu, bạn đang sử dụng phiên bản cũ hơn 26.6 và cần nâng cấp trước khi tiếp tục.

Nếu bạn có tệp giấy phép, hãy áp dụng nó một lần khi khởi động ứng dụng, trước bất kỳ lời gọi tạo hoặc nhận dạng nào:

from aspose.barcode import License

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

2. Đặt chế độ mã hoá cho mỗi đoạn bằng QrExtCodetextBuilder

QrExtCodetextBuilder giữ một danh sách có thứ tự các đoạn. Mỗi lần gọi sẽ nối dữ liệu cùng với chế độ mã hoá mà nó nên lưu, và get_extended_codetext() ghép chúng thành chuỗi định dạng mở rộng mà trình tạo hiểu.

1. Nhập các lớp tạo mã.
2. Tạo một QrExtCodetextBuilder.
3. Thêm một đoạn số với QrExtCompactionMode.NUMERIC.
4. Thêm một đoạn chữ‑số với QrExtCompactionMode.ALPHA_NUMERIC.
5. Thêm một đoạn byte với QrExtCompactionMode.BYTES.
6. Thêm một đoạn Kanji với QrExtCompactionMode.KANJI.
7. Lấy đoạn mã mở rộng đã kết hợp.

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

Giải thích

• Mỗi lời gọi add_codetext_with_compaction_mode đặt chế độ mã hoá cho một đoạn. Thứ tự quan trọng — bộ giải mã trả về các đoạn được nối lại theo trình tự bạn đã thêm chúng.
• Bộ ký tự alphanumeric được thiết kế cố ý hẹp: chữ số, chữ hoa A‑Z, dấu cách và $%*+-./:. Vì vậy ASPOSE2026 phù hợp với chế độ alphanumeric nhưng aspose2026 thì không. Các chữ thường không nằm trong bộ, vì vậy đoạn đó phải sử dụng BYTES. Việc truyền chữ thường vào ALPHA_NUMERIC là lỗi phổ biến nhất khi đặt chế độ theo cách này.
• Đoạn Kanji sử dụng \u3062 trở đi, là hiragana chứ không phải kanji thực sự. Chế độ Kanji bao phủ phạm vi byte đôi Shift‑JIS, bao gồm cả kana, vì vậy chúng được mã hoá thành 13 bit mỗi ký tự thay vì 24 bit mà chế độ byte sẽ tiêu tốn cho mỗi ký tự dưới dạng UTF‑8.
• get_extended_codetext() tạo ra chuỗi mà trình tạo phân tích trong chế độ EXTENDED. In nó bằng repr() là việc đáng làm một lần — nó cho bạn thấy cú pháp selector mà builder phát ra, chính là những gì phần phụ tiếp theo viết bằng tay.

3. Đặt chế độ mã hoá Inline, không dùng Builder

Khi đoạn mã nguồn xuất phát bên ngoài mã Python của bạn, bạn có thể đặt chế độ cho mỗi đoạn trực tiếp bằng một bộ chọn. Mỗi dấu đánh dấu có tiền tố dấu gạch chéo ngược điều khiển mọi ký tự cho đến khi dấu đánh dấu tiếp theo xuất hiện:

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

Lưu ý việc thoát ký tự. Trong một chuỗi Python thông thường, "\num" không phải là một selector — nó là một ký tự xuống dòng tiếp theo là um. Các chuỗi thô (r"...") tránh được vấn đề này, nhưng một chuỗi thô cũng ngăn các escape \u, vì vậy dòng Kanji ở trên sử dụng một chuỗi thông thường với \\kanji thay vì. Cạm bẫy escape này là lập luận thực tế để ưu tiên builder trong phần 2.

4. Tạo mã QR Barcode ở chế độ EXTENDED

Thiết lập chế độ mỗi đoạn không có hiệu lực cho đến khi bộ tạo được chỉ định đọc chúng. Nếu không có QREncodeMode.EXTENDED, thông tin đoạn sẽ bị bỏ qua và các dấu chọn sẽ được mã hoá dưới dạng văn bản tải trọng nguyên văn.

1. Tạo một BarcodeGenerator với EncodeTypes.QR và chuỗi mã mở rộng.
2. Đặt encode_mode thành QREncodeMode.EXTENDED.
3. Cấu hình độ phân giải và, tùy chọn, mức sửa lỗi và lề.
4. Lưu mã vạch dưới dạng PNG không mất dữ liệu.

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

Giải thích

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED là dòng kích hoạt việc phân tích đoạn. Bỏ nó đi và trình tạo sẽ tạo ra một mã QR hợp lệ, có thể quét được chứa văn bản nguyên gốc \num1234567... — vì vậy phần phụ đề tiếp theo sẽ xác minh thay vì giả định.
• gen.parameters.resolution = 300 render ở độ phân giải in. Các ký hiệu hướng tới máy in nhãn hoặc artwork bao bì nên được tạo ở kích thước cuối cùng, không nên phóng to sau này, vì điều đó làm mềm các cạnh mô-đun.
• save ghi ra PNG không mất dữ liệu. Tránh JPEG cho bất kỳ ký hiệu 2D nào — các artefact nén của nó làm mờ lưới mô-đun mà bộ giải mã lấy mẫu.

5. Xác minh chế độ mã hoá đã được áp dụng

Việc tạo thành công không chứng minh gì về việc các chế độ per‑segment có được áp dụng hay không. Bước giải mã là điều tách biệt một ký hiệu được mã hoá đúng với một ký hiệu mang các dấu hiệu chọn làm dữ liệu.

1. Khởi tạo một BarCodeReader với đường dẫn tệp và DecodeType.QR.
2. Hiển thị kết quả để một lần đọc thất bại có thể nhìn thấy.
3. So sánh văn bản đã giải mã với sự nối chuỗi mong đợi.

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)

Giải thích

• DecodeType.QR giới hạn việc nhận dạng chỉ các ký hiệu QR, điều này nhanh hơn so với việc quét mọi ký hiệu được hỗ trợ và ngăn một ký hiệu bị hỏng được giải mã thành một thứ khác.
• list(...) làm cho trường hợp thất bại trở nên rõ ràng. Một lỗi nhận dạng trả về một iterable rỗng thay vì ném ngoại lệ, vì vậy một vòng lặp for không được bảo vệ trên một lần đọc thất bại sẽ kết thúc một cách im lặng và được coi là thành công.
• Kiểm tra một literal \num bắt gặp lỗi phổ biến nhất trong quy trình này: thiết lập các segment đúng nhưng quên thiết lập encode_mode.
• Payload đã giải mã là các segment thô được nối lại, với tất cả thông tin chế độ đã được tiêu thụ trong quá trình mã hoá. Các chế độ mã hoá là hướng dẫn cho bộ mã hoá, không phải là một phần của dữ liệu.

6. Đo Lường Liệu Việc Đặt Chế Độ Thủ Công Có Giúp Đỡ

Cài đặt chế độ mã hoá theo cách thủ công là một tối ưu, vì vậy hãy đo lường nó thay vì giả định. Tạo cùng một payload theo cả hai cách và so sánh:

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

Đếm số mô-đun dọc theo một cạnh của mỗi hình ảnh. Một ký hiệu QR phiên bản n có kích thước 17 + 4n mô-đun vuông, vì vậy phiên bản 2 là 25×25 và phiên bản 3 là 29×29. Nếu cả hai đều rơi vào cùng một phiên bản, phân tích tự động đã tìm ra phân đoạn tối ưu và việc đặt chế độ thủ công là gánh nặng bảo trì mà không mang lại lợi ích. Việc phát hiện điều này trước khi phát hành là một kết quả hữu ích, không phải một bước lãng phí.

Nhận giấy phép miễn phí

Aspose cung cấp một giấy phép tạm thời miễn phí giúp loại bỏ các hạn chế đánh giá và mở khóa đầy đủ chức năng để thử nghiệm. Yêu cầu một giấy phép từ trang giấy phép tạm thời của Aspose và áp dụng nó trước bất kỳ cuộc gọi tạo hoặc nhận dạng nào.

Tài Nguyên Bổ Sung Miễn Phí

• Tài liệu sản phẩm
• Tham chiếu API
• Ứng dụng mã vạch trực tuyến miễn phí

Kết luận

Thiết lập các chế độ mã hoá QR code trong Python phụ thuộc vào hai câu hỏi: đoạn nào sẽ được áp dụng chế độ nào, và làm thế nào để bạn thông báo cho trình tạo tuân theo lựa chọn đó. QrExtCodetextBuilder và QrExtCompactionMode trả lời câu hỏi đầu tiên trong mã ứng dụng; QREncodeMode.EXTENDED trả lời câu hỏi thứ hai ở trình tạo. Hướng dẫn này bao gồm cả API builder và cú pháp chọn lựa nội tuyến mà nó tạo ra, tạo một biểu tượng QR có bốn đoạn, xác minh payload đã giải mã, và đo kích thước so với chế độ tự động.

Ưu tiên sử dụng builder cho mã ứng dụng — nó bắt lỗi chế độ tại vị trí gọi thay vì tại bộ quét. Và giữ lại bước đo lường. Đặt chế độ thủ công thực sự mang lại lợi thế trên các tải trọng đồng nhất dài và gây mất lợi nhuận trên các tải trọng hỗn hợp ngắn, nơi chi phí chuyển đổi chế độ vượt quá khoản tiết kiệm. Tạo cả hai, so sánh số lượng mô-đun, và để kết quả quyết định mã nào bạn sẽ duy trì.

Câu hỏi thường gặp

1. Mã hóa chế độ QR là gì và tại sao tôi nên sử dụng? Chế độ mã hóa cho biết bộ tạo QR cách xử lý một đoạn dữ liệu — số, chữ và số, byte hoặc Kanji. Mỗi chế độ có mật độ dữ liệu khác nhau, vì vậy việc chọn chế độ phù hợp cho từng đoạn giúp giữ phiên bản QR, và do đó ký hiệu, ở kích thước nhỏ nhất có thể. Aspose.BarCode gọi chúng là các chế độ nén; đặc tả QR gọi chúng là các chế độ mã hóa.

2. Chế độ mã hoá nào mà QrExtCompactionMode hỗ trợ? QrExtCompactionMode cung cấp NUMERIC, ALPHA_NUMERIC, BYTES, và KANJI, phù hợp với bốn chế độ dữ liệu QR được định nghĩa trong ISO/IEC 18004.

3. Tôi có nên sử dụng QrExtCodetextBuilder hay các bộ chọn EXTENDED nội tuyến để đặt chế độ? Sử dụng builder cho mã ứng dụng. Nó được kiểm tra kiểu, tránh các lỗi escape dấu gạch chéo ngược, và tự động tạo mã mở rộng cho bạn. Các bộ chọn nội tuyến hữu ích khi mã văn bản đến từ cấu hình, cơ sở dữ liệu, hoặc hệ thống khác không thể gọi builder.

4. Chế độ mã hoá EXTENDED khác gì so với chế độ mã hoá QR tiêu chuẩn? Chế độ EXTENDED khiến trình tạo đọc văn bản mã như một loạt các đoạn đã được định nghĩa trước, mỗi đoạn có chế độ mã hoá riêng, thay vì thực hiện phát hiện chế độ tự động trên toàn bộ chuỗi.

5. Có thể thiết lập các chế độ mã hoá khác nhau cho các phần khác nhau của một mã QR không? Có. Thêm một vài đoạn vào QrExtCodetextBuilder, mỗi đoạn có một QrExtCompactionMode khác nhau, và trình xây dựng sẽ tạo ra một chuỗi mã mở rộng duy nhất bao phủ tất cả chúng.

6. Liệu mã QR được tạo với các chế độ mã hoá hỗn hợp có tương thích với các trình đọc tiêu chuẩn không? Có. Mã hoá đa đoạn là một phần của đặc tả QR, vì vậy bất kỳ máy quét tuân thủ nào cũng sẽ giải mã payload một cách chính xác và trả về dữ liệu đã nối lại.

7. Liệu việc đặt chế độ mã hoá thủ công có luôn tạo ra mã QR nhỏ hơn không? Không. Mỗi ranh giới đoạn đều tốn một chỉ báo chế độ và một trường đếm ký tự, vì vậy việc chia dữ liệu thành nhiều đoạn ngắn có thể làm ký hiệu lớn hơn. Việc chọn chế độ thủ công có lợi khi có các chuỗi dài, đồng nhất của dữ liệu số hoặc Kanji.

8. Tôi có cần giấy phép để thiết lập các chế độ mã hoá QR với QrExtCodetextBuilder không? Bạn có thể đánh giá API mà không có giấy phép, tuy nhiên sẽ chịu các hạn chế đánh giá. Một giấy phép tạm thời miễn phí từ trang web Aspose sẽ loại bỏ các hạn chế này trong quá trình thử nghiệm, và việc sử dụng trong môi trường sản xuất yêu cầu giấy phép đầy đủ.

9. Phiên bản nào của Aspose.BarCode for python-net hỗ trợ các API này? QrExtCodetextBuilder, QrExtCompactionMode, và QREncodeMode.EXTENDED có sẵn trong Aspose.BarCode for Python via .NET 26.6 và các phiên bản sau.

Đọc thêm

• Tạo mã vạch MaxiCode trong Python
• Xây dựng trình tạo mã vạch Code 93 trong Python
• Tạo mã vạch và mã QR có logo trong Python