ضبط أوضاع ترميز رمز الاستجابة السريعة في بايثون

كل مولد QR يختار وضع الترميز لك افتراضيًا، وفي معظم الأحيان يكون هذا الافتراضي مناسبًا. يتوقف كونه مناسبًا في اللحظة التي تحتاج فيها إلى التحكم فيه — معرف رقمي بجانب رمز المنتج، كتلة من النص الياباني لا تريد تخزينها كـ UTF-8، أو حمولة تحتاج فيها إلى الحصول على نفس البايتات في كل مرة تقوم فيها بإنشائها. يوضح هذا الدليل كيفية تعيين أوضاع ترميز رمز QR في Python بشكل صريح، باستخدام Aspose.BarCode for Python via .NET، بحيث يمكن لرمز QR واحد أن يحمل مقطعًا رقميًا، ومقطعًا أبجديًا رقميًا، ومقطعًا بايتًا، ومقطعًا كانجي — كلٌ مخزن في الوضع الذي يناسبه أفضل.

Aspose.BarCode تستدعي هذه وضعيات الضغط بأسماء API الخاصة بها (QrExtCompactionMode) وتسمى مواصفة QR نفسها وضعيات الترميز. إنهما نفس الأربع وضعيات تحت اسمين، وتستخدم هذه الدليل مصطلح “وضعية الترميز” طوال الوقت لأنه المصطلح الذي تستخدمه المواصفة ومعظم مكتبات QR للبايثون.

لماذا تؤثر أوضاع ترميز QR على حجم الرمز وموثوقية المسح

يتم تحديد الحجم الفعلي لرمز QR بناءً على عدد البتات التي تحتاجها الحمولة، وتعتمد عدد البتات لكل حرف بالكامل على وضع الترميز المستخدم لذلك الجزء. تحدد المواصفة أربعة أوضاع للبيانات ذات كثافات مختلفة بشكل ملحوظ:

معرّف مكوّن من 30 رقمًا يكلف تقريبًا 100 بت في الوضع الرقمي و240 بت في وضع البايت. غالبًا ما يكون هذا الفارق كافيًا لدفع الرمز إلى عدة إصدارات QR، والإصدار الأعلى يعني المزيد من الوحدات في نفس مساحة الطباعة — وحدات أصغر، ومعدل قراءة أقل على الكاميرات منخفضة الدقة، والتغليف المنحني، والملصقات البالية.

يُعالج اختيار الوضع التلقائي معظم الحمولات بشكل جيد. يصبح محدودًا عندما تعرف شكل بياناتك ولا يعرفه المحلل: سلسلة رقمية طويلة مقطوعة بحرف واحد، نص ياباني سيستهلك وضع البايت ثلاثة بايتات UTF-8 لكل حرف، أو معرف بتنسيق ثابت حيث تريد مخرجات حتمية عبر إصدارات المكتبة.

عندما يكون ضبط الوضع يدويًا مجديًا

تبديل الوضع ليس مجانياً. كل حد للقطاع يكتب مؤشر وضع مكوّن من أربعة بتات بالإضافة إلى حقل عدد الأحرف الذي يتراوح بين ثمانية إلى ستة عشر بتًا حسب إصدار QR. قد يؤدي تقسيم الحمولة إلى أقسام أكثر من اللازم إلى إنتاج رمز أكبر مقارنةً بترك المولد يقرر ذلك.

تحديد الوضع صراحةً يكون مفيدًا عندما:

• الحمولة تحتوي على سلاسل طويلة ومتجانسة — رقم تسلسلي مكوّن من 40 رقمًا، وفقرة من الكانجي.
• أنت تقوم بترميز النص الياباني وتريد وضع الكانجي بـ 13 بت لكل حرف بدلاً من وضع البايت بـ 24.
• تحتاج إلى مخرجات قابلة لإعادة الإنتاج ومتطابقة بايتًا للاختبارات الانحدارية أو للتحقق من صحة المجموع الاختباري.

عادةً لا يستحق التعقيد الإضافي للحمولات القصيرة، أو البيانات التي تتبدل نوعها كل بضعة أحرف، أو عناوين URL، التي يتعامل معها التحليل التلقائي بشكل جيد بالفعل. يوضح القسم الفرعي للقياس أدناه كيفية التحقق من الحالة التي أنت فيها.

طريقتان لتعيين أوضاع ترميز QR في Python

Aspose.BarCode يقدم مسارين لنفس النتيجة المشفرة، ومن المفيد معرفة سبب وجودهما قبل كتابة الكود.

المُنشئ هو الافتراضي الأفضل. QrExtCompactionMode.NUMERIC إما أن يكون موجودًا أو يرفع AttributeError فورًا، بينما كتابة خاطئة مثل \numm في سلسلة تتحول بصمت إلى بيانات حمولة ولا تظهر إلا عندما يقوم شخص ما بمسح الملصق. كلا النهجين يزودان نفس إعداد المولد QREncodeMode.EXTENDED، لذا يمكنك الانتقال بينهما دون تغيير أي شيء لاحقًا.

تعيين أوضاع ترميز رمز الاستجابة السريعة في بايثون: خطوة بخطوة

1. تثبيت وإعداد بيئة التطوير

Aspose.BarCode for Python via .NET هي مكتبة متعددة المنصات تدعم الإنشاء، والتعرف، والتلاعب بأكثر من 50 نوعًا من الرموز، بما في ذلك QR. قم بالتثبيت من PyPI:

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

تأكد من الإصدار، حيث تتطلب هذه الواجهات البرمجية الإصدار 26.6 أو أحدث:

pip show aspose-barcode

ثم تحقق من أن الاستيراد يتم حله. الحزمة ترتبط بوقت تشغيل .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. تعيين وضع الترميز داخل السطر، دون المُنشئ

عندما يكون نص الشيفرة مصدره خارج كود بايثون الخاص بك، يمكنك تعيين وضع كل جزء مباشرةً باستخدام محدد. كل علامة مسبوقة بشرطة مائلة عكسية تتحكم في كل حرف حتى تظهر العلامة التالية:

# 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 لأي رموز ثنائية الأبعاد — فآثار الضغط فيه تشوش شبكة الوحدات التي يقرأها المُفكك.

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 في بايثون يتلخص في سؤالين: أي جزء يحصل على أي وضع، وكيف تخبر المُولِّد باحترام هذا الاختيار. QrExtCodetextBuilder و QrExtCompactionMode يجيبان على السؤال الأول في كود التطبيق؛ QREncodeMode.EXTENDED يجيب على السؤال الثاني في المُولِّد. يغطي هذا الدليل كل من واجهة برمجة التطبيقات الخاصة بالبناء (builder API) وصياغة المحدد المضمنة التي ينتجها، حيث يتم إنشاء رمز QR مكوّن من أربعة أقسام، والتحقق من الحمولة المفكوكة، وقياس فرق الحجم مقارنةً بالوضع التلقائي.

يفضل استخدام الـ builder في شفرة التطبيق — فهو يلتقط أخطاء الوضع في موقع الاستدعاء بدلاً من الماسح. واحفظ خطوة القياس. ضبط الوضع يدويًا يُعد فوزًا حقيقيًا في الحمولات المتجانسة الطويلة وخسارة صافية في الحمولات المختلطة القصيرة حيث يتجاوز عبء تبديل الوضع المدخرات. أنشئ كلاهما، قارن عدد الوحدات، ودع النتيجة تقرر أي شفرة تحتفظ بها.

الأسئلة المتكررة

1. ما هو وضع ترميز رمز QR ولماذا قد أستخدمه؟ يحدد وضع الترميز كيفية تعامل مولد QR مع جزء من البيانات — رقمي، أبجدي رقمي، بايت، أو كانجي. لكل وضع كثافة بيانات مختلفة، لذا اختيار الوضع المناسب لكل جزء يحافظ على نسخة QR، وبالتالي الرمز، بأصغر حجم ممكن. Aspose.BarCode يطلق على هذه الأوضاع أوضاع الضغط؛ مواصفة QR تسميها أوضاع الترميز.

2. ما هي أوضاع الترميز التي يدعمها QrExtCompactionMode؟ QrExtCompactionMode يوفر NUMERIC، ALPHA_NUMERIC، BYTES، و KANJI، مطابقةً لأربع أوضاع بيانات QR المعرفة في ISO/IEC 18004.

3. هل يجب عليّ استخدام QrExtCodetextBuilder أو محددات EXTENDED المضمنة لتعيين الوضع؟ استخدم الـ builder لتطبيقات الكود. إنه type-checked، يتجنب أخطاء backslash escaping، ويجمع الـ extended codetext لك. الـ inline selectors مفيدة عندما يأتي الـ codetext من التكوين، قاعدة بيانات، أو نظام آخر لا يمكنه استدعاء الـ builder.

4. كيف يختلف وضع الترميز EXTENDED عن وضع الترميز القياسي لـ QR؟ وضع EXTENDED يجعل المولد يقرأ نص الرمز كسلسلة من المقاطع المعرفة مسبقًا، كل منها لديه وضع الترميز الخاص به، بدلاً من تشغيل الكشف التلقائي عن الوضع عبر السلسلة بأكملها.

5. هل يمكنني تعيين أوضاع ترميز مختلفة لأجزاء مختلفة من رمز QR واحد؟ نعم. أضف عدة مقاطع إلى QrExtCodetextBuilder، كل منها بوضع QrExtCompactionMode مختلف، ويولد المُنشئ نص ترميز ممتد واحد يغطي جميعها.

6. هل رمز QR الذي تم إنشاؤه باستخدام أوضاع ترميز مختلطة متوافق مع القارئات القياسية؟ نعم. الترميز متعدد القطاعات هو جزء من مواصفة QR، لذا أي ماسح ضوئي متوافق يقوم بفك تشفير الحمولة بشكل صحيح ويعيد البيانات المدمجة.

7. هل يؤدي ضبط وضع الترميز يدويًا دائمًا إلى إنتاج رمز QR أصغر؟ لا. كل حد فاصل للقطعة يكلف مؤشر وضع وحقل عدد الأحرف، لذا فإن تقسيم البيانات إلى العديد من القطع القصيرة يمكن أن يجعل الرمز أكبر. اختيار الوضع يدويًا يكون مفيدًا في سلاسل طويلة ومتجانسة من البيانات الرقمية أو كانجي.

8. هل أحتاج إلى ترخيص لتعيين أوضاع ترميز QR باستخدام QrExtCodetextBuilder؟ يمكنك تقييم الـ API بدون ترخيص، مع مراعاة قيود التقييم. ترخيص مؤقت مجاني من موقع Aspose يرفع تلك القيود أثناء الاختبار، ويتطلب الاستخدام في الإنتاج ترخيصًا كاملاً.

9. ما هو الإصدار من Aspose.BarCode for python-net الذي يدعم هذه الواجهات البرمجية؟ QrExtCodetextBuilder، QrExtCompactionMode، و QREncodeMode.EXTENDED متاحة في Aspose.BarCode for Python via .NET 26.6 وما بعده.

اقرأ المزيد

• إنشاء باركود MaxiCode في بايثون
• إنشاء مولد باركود Code 93 في بايثون
• إنشاء باركود ورمز QR مع شعار في بايثون