在 Python 中設定 QR 代碼編碼模式

每個 QR 產生器預設會為您選擇編碼模式，而大多數情況下這個預設已足夠。當您需要對其進行控制時——例如在產品代碼旁的數字 ID、您不想以 UTF-8 儲存的日文文字區塊，或是每次產生時都需要相同位元組的有效負載——情況就不再適用。此指南說明如何在 Python 中明確 設定 QR 代碼的編碼模式，使用 Aspose.BarCode for Python via .NET，讓單一 QR 符號能同時承載數字段、字母數字段、位元組段以及漢字段——每個段落皆以最適合的模式儲存。

Aspose.BarCode 在其自己的 API 名稱 (QrExtCompactionMode) 中稱這些為 compaction modes，而 QR 規範本身稱它們為 encoding modes。它們是同樣的四種模式，只是名稱不同，本文指南全程使用「encoding mode」這個術語，因為規範和大多數 Python QR 庫都使用這個詞。

為什麼 QR 編碼模式會影響符號大小和掃描可靠性

QR 码的實體大小取決於其有效負載所需的位元數，而每個字元的位元數完全取決於該段使用的編碼模式。規範定義了四種資料模式，具有顯著不同的密度：

30 位數的識別碼在數字模式下大約需要 100 位元，在位元組模式下則約需 240 位元。這個差距通常足以將符號提升至更高的 QR 版本，而更高的版本意味著在相同的印刷區域內有更多的模組——模組更小，且在低解析度相機、彎曲的包裝以及磨損的標籤上讀取率較低。

自動模式選擇能很好地處理大多數有效負載。但當您了解資料的形態而分析器卻不了解時，就會受到限制：例如被單個字母打斷的長數字序列、字節模式會為每個字符消耗三個 UTF-8 位元組的日文文本，或是您希望在不同庫版本間產生確定性輸出的固定格式識別碼。

當手動設定模式值得時

模式切換不是免費的。每個段落邊界都會寫入四位元模式指示符，加上根據 QR 版本而定的八至十六位元字符計數欄位。過度分段的有效負載可能會產生比讓生成器自行決定更大的符號。

明確設定模式在以下情況下會有回報：

• 負載包含長且同質的序列——一個 40 位數的序號，一段漢字段落。
• 您正在編碼日文文本，想要使用每字元 13 位元的漢字模式，而不是每字元 24 位元的位元組模式。
• 您需要可重現、位元組相同的輸出，以便進行回歸測試或校驗和驗證。

對於短負載、每幾個字元就交替類型的資料，或是 URL（自動分析已能很好處理），通常不值得增加複雜性。下面的測量子節顯示如何檢查您所處的情況。

在 Python 中設定 QR 編碼模式的兩種方法

Aspose.BarCode 提供兩條通往相同編碼結果的路徑，在編寫程式碼之前了解兩者為何同時存在是值得的。

建構器是較好的預設。 QrExtCompactionMode.NUMERIC 要麼存在，要麼立即拋出 AttributeError，而在字串中錯誤拼寫為 \numm 時，會悄悄變成有效負載資料，僅在有人掃描標籤時才會顯現。兩種方法都使用相同的 QREncodeMode.EXTENDED 產生器設定，因此您可以在它們之間切換，而無需更改下游的任何內容。

在 Python 中設定 QR Code 編碼模式：逐步指南

1. 安裝並準備開發環境

Aspose.BarCode for Python via .NET 是一個跨平台庫，支援超過 50 種條碼符號（包括 QR）的生成、識別和操作。從 PyPI 安裝：

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

確認版本，因為這些 API 需要 26.6 或更新版本：

pip show aspose-barcode

然後驗證 import 是否解析成功。該套件綁定到 .NET 執行環境，因此成功的 import 能告訴你比磁碟上文件的存在更多資訊：

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

如果缺少 EXTENDED，表示您使用的版本早於 26.6，需要先升級才能繼續。

如果您有授權檔案，請在應用程式啟動時一次性套用，於任何產生或辨識呼叫之前：

from aspose.barcode import License

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

2. 使用 QrExtCodetextBuilder 為每個段落設定編碼模式

QrExtCodetextBuilder 保存有序的段列表。每次调用都会将数据与应存储的编码模式一起追加，并且 get_extended_codetext() 会将它们组装成生成器能够理解的扩展格式字符串。

1. 匯入生成類別。
2. 建立一個 QrExtCodetextBuilder。
3. 使用 QrExtCompactionMode.NUMERIC 新增數字段。
4. 使用 QrExtCompactionMode.ALPHA_NUMERIC 新增字母數字段。
5. 使用 QrExtCompactionMode.BYTES 新增位元組段。
6. 使用 QrExtCompactionMode.KANJI 新增漢字段。
7. 取得合併的擴充代碼文字。

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

說明

• 每個 add_codetext_with_compaction_mode 呼叫都會為一個段設定編碼模式。順序很重要——解碼器會按照您添加它們的順序返回串接的段。
• 字母數字集合被刻意設得很窄：數字、全大寫 A‑Z、空格，以及 $%*+-./:。這就是為什麼 ASPOSE2026 符合字母數字模式，而 aspose2026 不符合。小寫字母不在集合內，因此該段必須使用 BYTES。將小寫字母傳遞給 ALPHA_NUMERIC 是以此方式設定模式時最常見的錯誤。
• Kanji 段使用 \u3062 起始的字符，這些是平假名而非真正的漢字。Kanji 模式涵蓋 Shift‑JIS 雙位元組範圍，該範圍包括假名，因此這些字符每個以 13 位元編碼，而不是以 UTF‑8 的位元組模式所需的 24 位元。
• get_extended_codetext() 產生生成器在 EXTENDED 模式下解析的字串。使用 repr() 列印一次是值得的——它會顯示建構器輸出的選擇器語法，這正是下一小節手動撰寫的內容。

3. 在不使用 Builder 的情況下內嵌設定編碼模式

當程式碼文字來源於您的 Python 程式碼之外時，您可以使用選擇器直接設定每個段落的模式。每個以反斜線為前綴的標記會控制其後的所有字元，直到出現下一個標記為止：

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

注意轉義。
在普通的 Python 字串中，"\num" 不是選擇器——它是一個換行符，後面接著 um。
原始字串（r"..."）避免了此問題，但原始字串同時也會阻止 \u 轉義，這就是為什麼上面的漢字行使用了帶有 \\kanji 的普通字串的原因。
這個轉義陷阱是實際上在第 2 節中偏好使用建構器的論點。

4. 產生 EXTENDED 模式的 QR 條碼

設定每段模式在未告訴產生器讀取它們之前不會產生任何效果。若未使用 QREncodeMode.EXTENDED，段落資訊將被忽略，且選擇器標記會被編碼為文字負載的字面文本。

1. 建立一個使用 EncodeTypes.QR 且包含擴展代碼文字的 BarcodeGenerator。
2. 將 encode_mode 設定為 QREncodeMode.EXTENDED。
3. 設定解析度，並可選擇性地設定錯誤更正等級和邊距。
4. 將條碼儲存為無損 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")

說明

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED 是啟用段落解析的行。將其省略，生成器會產生一個有效且可掃描的 QR 代碼，包含文字 \num1234567... — 這也是為什麼下一小節會驗證而不是假設。
• gen.parameters.resolution = 300 以列印解析度渲染。針對標籤印表機或包裝藝術的符號應以最終尺寸生成，而不是之後再放大，因為放大會使模組邊緣變得柔和。
• save 會寫入無損 PNG。避免對任何 2D 符號使用 JPEG — 其壓縮雜訊會模糊解碼器取樣的模組格線。

5. 驗證已套用編碼模式

成功的生成並不證明每段模式是否生效。解碼步驟是將正確編碼的符號與作為數據攜帶選擇器標記的符號區分開來的關鍵。

1. 使用檔案路徑和 DecodeType.QR 初始化 BarCodeReader。
2. 具現化結果，以便顯示讀取失敗的情況。
3. 將解碼後的文字與預期的串接結果進行比較。

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)

說明

• DecodeType.QR 限制辨識僅為 QR 符號，這比掃描所有支援的條碼類型更快，且可防止將畸形符號解碼成其他內容。
• list(...) 使失敗情況明確。辨識失敗會回傳空的可疊代物件而不是拋出例外，因此對失敗讀取的未加保護的 for 迴圈會靜默結束，且被視為成功。
• 檢查文字字面量 \num 可捕捉此工作流程中最常見的錯誤：正確設定段落卻忘記設定 encode_mode。
• 解碼後的有效負載是原始段落的串接，所有模式資訊在編碼時已被消耗。編碼模式是給編碼器的指令，並非資料的一部分。

6. 測量手動設定模式是否有幫助

手動設定編碼模式是一種優化，請測量其效果而不是僅僅假設。以兩種方式產生相同的有效負載並進行比較：

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

計算每張圖像一邊的模組數。QR 版本 n 符號是 17 + 4n 模組的正方形，因此版本 2 為 25×25，版本 3 為 29×29。如果兩者落在相同的版本，自動分析已經找到了最佳分割，手動設定模式僅會增加維護負擔而無收益。在出貨前發現此情況是一個有用的結果，而非浪費的步驟。

取得免費授權

Aspose 提供臨時免費許可證，可解除評估限制，並解鎖完整功能以供測試。請從 Aspose 臨時許可證頁面 取得，並在任何生成或識別調用之前套用它。

免費額外資源

• 產品文件
• API 參考
• 免費線上條碼應用程式

結論

在 Python 中設定 QR 代碼的編碼模式主要涉及兩個問題：哪個段落使用哪種模式，以及如何告訴產生器遵循此選擇。QrExtCodetextBuilder 和 QrExtCompactionMode 在應用程式碼中回答第一個問題；QREncodeMode.EXTENDED 在產生器層面回答第二個問題。本指南涵蓋了建構器 API 以及它產生的內嵌選擇器語法，生成四段式 QR 符號，驗證解碼後的有效負載，並測量相較於自動模式的大小差異。

在應用程式碼中偏好使用 builder —— 它能在呼叫端捕捉模式錯誤，而不是在掃描器處。並且保留測量步驟。手動設定模式在長且同質的有效負載上是真正的優勢，而在短且混合的情況下則會因模式切換開銷超過節省而造成淨損失。生成兩者，比較模組計數，讓結果決定你要維護哪段程式碼。

常見問題

1. 什麼是 QR 代碼編碼模式，為什麼要使用它？ 編碼模式告訴 QR 產生器如何處理資料段——數字、字母數字、位元組或漢字。每種模式的資料密度不同，因此為每個段選擇合適的模式可保持 QR 版本，從而使符號盡可能小。Aspose.BarCode 將這些稱為壓縮模式；QR 規範則稱之為編碼模式。

2. QrExtCompactionMode 支援哪些編碼模式？ QrExtCompactionMode 提供 NUMERIC、ALPHA_NUMERIC、BYTES 和 KANJI，與 ISO/IEC 18004 中定義的四種 QR 資料模式相匹配。

3. 我應該使用 QrExtCodetextBuilder 還是內聯 EXTENDED 選擇器來設定模式？ 在應用程式碼中使用 builder。它具備型別檢查，避免反斜線轉義錯誤，並為您組合擴充的 codetext。當 codetext 來自設定、資料庫或其他無法呼叫 builder 的系統時，內聯選擇器會很有用。

4. EXTENDED 編碼模式與標準 QR 編碼模式有何不同？ EXTENDED 模式使生成器將代碼文本視為一系列預定義的段落，每個段落都有自己的編碼模式，而不是對整個字串執行自動模式檢測。

5. 我可以為同一 QR 代碼的不同部分設定不同的編碼模式嗎？ 可以。將多個段落添加到 QrExtCodetextBuilder，每個段落使用不同的 QrExtCompactionMode，構建器會產生一個覆蓋所有段落的單一擴展代碼文本。

6. 使用混合編碼模式生成的 QR 代碼是否與標準讀取器兼容？ 是的。多段編碼是 QR 規範的一部分，因此任何符合規範的掃描器都會正確解碼有效負載並返回串接的資料。

7. 手動設定編碼模式是否總是會產生較小的 QR 代碼？ 不會。每個段落邊界都需要模式指示符和字元計數欄位，因此將資料拆分為許多短段可能會使符號變大。手動模式選擇在長且同質的數字或漢字資料序列中才會有益。

8. 我需要許可證才能使用 QrExtCodetextBuilder 設定 QR 編碼模式嗎？ 您可以在沒有許可證的情況下評估 API，但需遵守評估限制。從 Aspose 網站獲得的免費臨時許可證可在測試期間解除這些限制，而正式生產環境則需要完整許可證。

9. 哪個版本的 Aspose.BarCode for python-net 支援這些 API？ QrExtCodetextBuilder、QrExtCompactionMode 和 QREncodeMode.EXTENDED 可在 Aspose.BarCode for Python via .NET 26.6 及更高版本中使用。

閱讀更多

• 在 Python 中生成 MaxiCode 條碼
• 在 Python 中構建 Code 93 條碼生成器
• 在 Python 中生成帶徽標的條碼和 QR 代碼