הגדר מצבי קידוד של קוד QR בפייתון

כל יוצר QR בוחר עבורך מצב קידוד כברירת מחדל, וברוב המקרים ברירת המחדל הזו מספיקה. היא מפסיקה להיות מספיקה ברגע שאתה צריך שליטה עליה — מזהה מספרי ליד קוד מוצר, קטע טקסט יפני שאתה לא רוצה לאחסן כ‑UTF‑8, או מטען שבו אתה צריך את אותם הבייטים בכל פעם שאתה יוצר אותו. מדריך זה מראה כיצד להגדיר מצבי קידוד QR ב-Python במפורש, באמצעות Aspose.BarCode for Python via .NET, כך שסמל QR יחיד יכול לשאת קטע מספרי, קטע אלפאנומרי, קטע בתים וקטע קאנג’י — כל אחד מאוחסן במצב המתאים לו ביותר.

Aspose.BarCode קורא למצבי compaction modes בשם API שלו (QrExtCompactionMode) והמאפיין של QR עצמו קורא להם encoding modes. מדובר באותם ארבעה מצבים תחת שני שמות, וההדרכה הזו משתמשת במונח “encoding mode” לאורך כל הטקסט מכיוון שזה המונח שהמאפיין ורוב ספריות QR של Python משתמשים בו.

למה מצבי קידוד QR משפיעים על גודל הסמל ואמינות הסריקה

הגודל הפיזי של קוד QR נקבע על פי מספר הביטים שהמטען שלו צריך, והביטים לכל תו תלויים לחלוטין במצב הקידוד שבו משתמשים עבור אותו קטע. המפרט מגדיר ארבעה מצבי נתונים עם צפיפויות שונות במובהק:

מזהה של 30 ספרות עולה בערך 100 ביט במצב מספרי ו‑240 ביט במצב בתים. הפער הזה לרוב מספיק כדי לדחוף את הסמל כמה גרסאות QR, וגרסה גבוהה יותר משמעותה יותר מודולים באותו שטח מודפס — מודולים קטנים יותר, וקצב קריאה נמוך יותר במצלמות ברזולוציה נמוכה, אריזות מעוקלות ותוויות שחוקות.

בחירת המצב האוטומטית מתמודדת היטב עם רוב המטענים. היא הופכת למגבלה כאשר אתה יודע את צורת הנתונים שלך והאנלייזר אינו יודע זאת: רצף מספרי ארוך שמופרד על ידי אות אחת, טקסט יפני שבו מצב הבייט היה צורך שלושה בתים ב‑UTF‑8 לכל תו, או מזהה בפורמט קבוע שבו אתה רוצה פלט דטרמיניסטי בין גרסאות הספרייה.

כאשר קביעת המצב ידנית היא כדאית

מעבר מצבי אינו חינמי. כל גבול של קטע כותב אינדיקטור מצב של ארבעה ביטים בתוספת שדה ספירת תווים של שמונה עד שש‑עשרה ביטים, תלוי בגרסת ה‑QR. חיתוך יתר של המטען עלול ליצור סימן גדול יותר מאשר לתת למייצר להחליט.

הגדרת המצב במפורש משתלמת כאשר:

• המטען מכיל רצפים ארוכים ואחידים — סדרה של 40 ספרות, פסקה של קאנג’י.
• אתה מקודד טקסט יפני ורוצה מצב קאנג’י של 13 סיביות לכל תו במקום מצב בתים של 24.
• אתה צריך פלט חוזר, זהה בתים, לבדיקות רגרסיה או לאימות סכום ביקורת.

בדרך כלל לא כדאי את המורכבות המוגברת עבור מטענים קצרים, נתונים שמשנים סוג כל כמה תווים, או כתובות URL, שהניתוח האוטומטי כבר מתמודד איתן היטב. תת‑הפרק של המדידה למטה מראה כיצד לבדוק באיזה מקרה אתה נמצא.

שתי דרכים להגדיר מצבי קידוד QR בפייתון

Aspose.BarCode מציע שני מסלולים לתוצאה המוצפנת זהה, וכדאי לדעת למה שני המסלולים קיימים לפני כתיבת קוד.

הבונה היא ברירת המחדל הטובה יותר. QrExtCompactionMode.NUMERIC או קיים או מעלה AttributeError מיידית, בעוד שהקלדה שגויה של \numm במחרוזת הופכת בשקט לנתוני מטען ומופיעה רק כאשר מישהו סורק את התווית. שתי הגישות מזינות את אותה הגדרת מחולל QREncodeMode.EXTENDED, כך שניתן לעבור ביניהן מבלי לשנות דבר במערכת המשנית.

הגדרת מצבי קידוד QR Code ב-Python: שלב אחר שלב

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

לאחר מכן אמת שהייבוא נפתר. החבילה קשורה ל‑runtime של .NET, ולכן ייבוא מוצלח אומר לך יותר מנוכחות הקבצים על הדיסק:

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 היא הטעות הנפוצה ביותר בעת הגדרת מצבים בצורה זו.
• הקטע בקאנג’י משתמש ב‑\u3062 והלאה, שהם היראגנה ולא קאנג’י אמיתי. מצב קאנג’י מכסה את טווח הבייטים הכפולים של Shift‑JIS, הכולל קנה, ולכן קטעים אלה מקודדים ב‑13 ביט לכל אחד במקום ב‑24 ביט שמצב הבייט היה משתמש בו עבור כל תו ב‑UTF‑8.
• get_extended_codetext() מייצר את המחרוזת שהמחולל מפענח במצב EXTENDED. הדפסתה עם repr() שווה לעשות זאת פעם אחת — היא מציגה את תחביר הבחירה שהבונה מפיק, שזה בדיוק מה שהפסקה הבאה כותבת ידנית.

3. הגדר את מצב הקידוד באופן מקוון, ללא הבונה

כאשר קוד הטקסט מגיע מחוץ לקוד ה‑Python שלך, אתה יכול להגדיר את מצב כל קטע ישירות באמצעות בורר. כל סימון שמתחיל ב‑backslash שולט בכל תו עד שהסימון הבא מופיע:

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

שים לב לבריחה. במחרוזת פייתון רגילה, "\num" אינו בורר — הוא שורת חדשה ולאחריה um. מחרוזות גולמיות (r"...") נמנעות מהבעיה, אך מחרוזת גולמית גם חוסמת בריחות \u, ולכן שורת הקאנג’י למעלה משתמשת במחרוזת רגילה עם \\kanji במקום זאת. מלכודת הבריחה הזו היא הטיעון המעשי לבחירת הבונה בסעיף 2.

4. יצירת קוד QR במצב EXTENDED

הגדרת מצבי פר‑סגמנט אינה משפיעה עד שהמחולל מתבקש לקרוא אותם. ללא QREncodeMode.EXTENDED, מידע הסגמנט מתעלם והסמנים של הבורר מקודדים כטקסט מטען מילולי.

1. צור BarcodeGenerator עם EncodeTypes.QR וטקסט הקוד המורחב.
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 ללא אובדן. יש להימנע מ‑JPEG עבור כל סימבוליה דו‑ממדית — artefacts של הדחיסה מטשטשים את רשת המודולים שהמפענח מדגם.

5. אמת שהופעל מצב הקידוד

הייצור המוצלח אינו מוכיח דבר לגבי האם מצבי הפר‑סגמנט נכנסו לתוקף. שלב הפענוח הוא מה שמפריד בין סמל מקודד כראוי לבין סמל שנושא סמני בורר כנתונים.

1. אתחל את BarCodeReader עם נתיב הקובץ ו-DecodeType.QR.
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(...) עושה את מקרה הכשל מפורש. כשל בזיהוי מחזיר iterable ריק במקום לזרוק חריגה, ולכן לולאת 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
• אפליקציות ברקוד חינמיות באינטרנט

סיכום

הגדרת מצבי קידוד QR בקוד Python מסתכמת בשתי שאלות: איזה קטע מקבל איזה מצב, וכיצד מודיעים למחולל לכבד את הבחירה הזו. QrExtCodetextBuilder ו‑QrExtCompactionMode עונים על השאלה הראשונה בקוד היישום; QREncodeMode.EXTENDED עונה על השנייה במחולל. מדריך זה כיסה הן את ה‑API של הבונה והן את תחביר בורר השורה הישירה שהוא מייצר, יוצר סמל QR בעל ארבעה קטעים, מאמת את המטען המפוענח, ומודד את הפרש הגודל מול המצב האוטומטי.

העדיף להשתמש בבונה עבור קוד יישום — הוא תופס שגיאות מצב במקום הקריאה במקום בסורק. ושמור על שלב המדידה. הגדרת המצב ידנית היא יתרון משמעותי על עומסים הומוגניים ארוכים והפסד נטו על עומסים מעורבים קצרים שבהם עלות המעבר בין מצבים חורגת מהחיסכון. צור את שני המקרים, השווה את ספירות המודולים, ותן לתוצאה להחליט איזה קוד אתה מתחזק.

שאלות נפוצות

1. מהו מצב קידוד של קוד QR ולמה להשתמש בו? מצב קידוד מודיע למייצר ה‑QR כיצד לטפל במקטע נתונים — מספרי, אלפאנומרי, בתים או קאנג’י. לכל מצב יש צפיפות נתונים שונה, ולכן בחירת המצב המתאים לכל מקטע משמרת את גרסת ה‑QR, ולכן גם את הסמל, קטנה ככל האפשר. Aspose.BarCode קורא למצביים אלה מצבי דחיסה; מפרט ה‑QR קורא להם מצבי קידוד.

2. אילו מצבי קידוד תומך QrExtCompactionMode? QrExtCompactionMode מספק NUMERIC, ALPHA_NUMERIC, BYTES ו-KANJI, תואם לארבעת מצבי הנתונים של QR המוגדרים ב-ISO/IEC 18004.

3. האם עלי להשתמש בQrExtCodetextBuilder או בבוחרים EXTENDED משולבים כדי להגדיר את המצב? השתמש בבונה עבור קוד היישום. הוא נבדק בטיפוס, מונע טעויות ברצף בריחה של קו נטוי אחורי, ומרכיב עבורך את הקוד המורחב. בוחרים משולבים שימושיים כאשר הקוד מגיע מהגדרות, ממסד נתונים, או ממערכת אחרת שאינה יכולה לקרוא לבונה.

4. כיצד מצב מוד קידוד EXTENDED שונה ממוד קידוד QR הסטנדרטי?
   מוד EXTENDED גורם למחולל לקרוא את טקסט הקוד כסדרה של קטעים מוגדרים מראש, שלכל אחד יש מוד קידוד משלו, במקום לבצע זיהוי אוטומטי של המוד על פני כל המחרוזת.

5. האם אני יכול להגדיר מצבי קידוד שונים לחלקים שונים של קוד QR אחד? כן. הוסף מספר קטעים לQrExtCodetextBuilder, כל אחד עם QrExtCompactionMode שונה, והבונה מייצרת טקסט קוד מורחב יחיד המכסה את כולם.

6. האם קוד QR שנוצר עם מצבי קידוד מעורבים תואם לקוראים סטנדרטיים? כן. קידוד מרובה‑קטעים הוא חלק ממפרט ה‑QR, ולכן כל סורק תואם מפענח את המטען בצורה נכונה ומחזיר את הנתונים המשולבים.

7. האם הגדרת מצב הקידוד באופן ידני תמיד מייצרת קוד QR קטן יותר? לא. כל גבול של קטע דורש מציין מצב ושדה ספירת תווים, ולכן פיצול הנתונים למספר קטעים קצרים עלול לגרום לסמל להיות גדול יותר. בחירת מצב ידנית משתלמת ברצפים ארוכים והומוגניים של נתונים מספריים או קאנג’י.

8. האם אני צריך רישיון כדי להגדיר מצבי קידוד QR עם QrExtCodetextBuilder? אתה יכול להעריך את ה-API ללא רישיון, בכפוף למגבלות הערכה. רישיון זמני חינמי מהאתר של Aspose מסיר את המגבלות הללו במהלך הבדיקה, ושימוש בייצור דורש רישיון מלא.

9. איזו גרסה של Aspose.BarCode for python-net תומכת ב‑APIs האלה? QrExtCodetextBuilder, QrExtCompactionMode, ו-QREncodeMode.EXTENDED זמינים ב‑Aspose.BarCode for Python via .NET 26.6 ומעלה.

קרא עוד

• יצירת ברקוד MaxiCode ב-Python
• בניית גנרטור ברקוד Code 93 ב-Python
• יצירת ברקוד וקוד QR עם לוגו ב-Python