التحقق من صحة الإدخال ومعالجة الأخطاء

التحقق من صحة الإدخال ومعالجة الأخطاء

Aspose.BarCode FOSS لـ Python يتحقق من صحة جميع بيانات الإدخال قبل الترميز. كل رمزية لها فئة فرعية InputParser مخصصة تتحقق من مجموعات الأحرف، قيود الطول، وقواعد التنسيق. عندما تفشل عملية التحقق، ترفع المكتبة استثناءات ذات نوعية من تسلسل BarcodeError حتى يتمكن المستدعون من التمييز بين مشاكل الإدخال، فشل الترميز، ومشكلات العرض.

طبقة InputParser

كل رمزية تسجل تنفيذ InputParser. عندما تستدعي BarcodeService.generate()، يعمل المحلل أولاً، وينتج NormalizedPayload أو يرفع InvalidInputError إذا كانت البيانات غير صالحة لتلك الرمزية.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Valid Code 128 input — passes the Code128InputParser
barcode = service.generate("code128", "VALID-DATA-001")

# Invalid EAN-13 input — too few digits
try:
    barcode = service.generate("ean13", "123")
except Exception as e:
    print(type(e).__name__, e)

كل محلل رمزية يتحقق من قواعد مختلفة:

• Code128InputParser — يتحقق من أن جميع الأحرف ضمن نطاق ASCII المدعوم من مجموعات أحرف Code 128
• Code39InputParser — يتحقق من الأحرف مقابل قاعدة Code 39 أو أبجدية ASCII الكاملة اعتمادًا على Code39Options.full_ascii
• Ean13InputParser — يتطلب بالضبط 12 أو 13 رقمًا عدديًا (الرقم 13 هو رقم التحقق)
• Ean8InputParser — يتطلب بالضبط 7 أو 8 أرقام عددية
• QrInputParser — يتحقق من صحة البيانات وفقًا للـ QrEncodeMode المحدد (NUMERIC، ALPHANUMERIC، BYTE، أو KANJI)
• UpcaInputParser — يتطلب بالضبط 11 أو 12 أرقام عددية
• UpceInputParser — يتطلب بالضبط 6 أو 7 أو 8 أرقام عددية مع نمط UPC-E صالح

التسلسل الهرمي BarcodeError

جميع الاستثناءات ترث من BarcodeError، التي توسّع Exception المدمج في Python. يسمح التسلسل الهرمي بكتل catch على مستويات مختلفة من التحديد:

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import (
    BarcodeError,
    InvalidInputError,
    EncodingError,
    SymbologyNotFoundError,
)

service = BarcodeService()

try:
    barcode = service.generate("code128", "TEST-001")
    svg = barcode.to_svg()
except InvalidInputError as e:
    print(f"Input rejected: {e}")
except EncodingError as e:
    print(f"Encoding failed: {e}")
except SymbologyNotFoundError as e:
    print(f"Unknown symbology: {e}")
except BarcodeError as e:
    print(f"Barcode error: {e}")

التحقق من صحة أسماء الرموز

SymbologyNotFoundError يُرفع عندما يتلقى BarcodeService.generate() اسم رموز غير مسجل. الـSymbologyRegistry يحل الأسماء بالاسم القانوني أو الاسم المستعار، لذا فإن "code128" و"Code128" و"CODE128" كلها تُحل إلى نفس التعريف.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import SymbologyNotFoundError

service = BarcodeService()

try:
    barcode = service.generate("invalid_type", "data")
except SymbologyNotFoundError as e:
    print(f"Not found: {e}")

التحقق من رقم التحقق

رموز EAN-13 و EAN-8 و UPC-A و UPC-E تحسب أرقام التحقق تلقائيًا. إذا قمت بتمرير البيانات الكاملة بما فيها رقم التحقق، فإن المحلل يتحقق منها مقابل القيمة المحسوبة. خاصية allow_check_digit_input على Ean13Options وEan8Options تتحكم في هذا السلوك.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss import Ean13Options

service = BarcodeService()

# 12 digits — check digit computed automatically
barcode = service.generate("ean13", "590123412345")

# 13 digits — parser verifies the 13th digit matches the computed value
barcode = service.generate(
    "ean13", "5901234123457",
    encode=Ean13Options(allow_check_digit_input=True),
)

نصائح وأفضل الممارسات

• التقط InvalidInputError لنماذج الإدخال الموجهة للمستخدم حيث قد لا تستوفي البيانات متطلبات الرموز
• استخدم BarcodeError كملحق شامل فقط عندما لا تحتاج إلى التمييز بين أنواع الأخطاء
• تحقق من اسم الرموز مقابل الرموز السبع المدعومة (code128, code39, ean13, ean8, qrcode, upca, upce) قبل استدعاء generate() لتجنب SymbologyNotFoundError
• بالنسبة لأكواد QR، اضبط encoding_mode صراحةً عبر QrOptions عندما تحتوي البيانات على أحرف غير ASCII
• دع المكتبة تحسب أرقام التحقق بدلاً من تزويدها يدويًا — هذا يتجنب الاختلافات

المشكلات الشائعة

FAQ

كيف أتحقق مما إذا كان اسم الترميز صالحًا قبل الإنشاء؟

استخدم BarcodeService.registry للوصول إلى SymbologyRegistry. استدعِ get_definition() والتقط SymbologyNotFoundError إذا لم يكن الاسم مسجلاً.

هل يمكنني تعطيل التحقق من أرقام التحقق لباركودات EAN؟

يقوم المحلل دائمًا بالتحقق من أرقام التحقق عندما تزود الإدخال بطوله الكامل (13 رقمًا لـ EAN-13، 8 لأجل EAN-8). لتجنب التحقق، زوِّد فقط أرقام البيانات (12 لـ EAN-13، 7 لـ EAN-8) ودع المكتبة تحسب رقم التحقق.

ماذا يحدث إذا قمت بتمرير بيانات ثنائية إلى ترميز باركود أحادي الأبعاد؟

InvalidInputError تم رفعه. Code 128، Code 39، EAN، وUPC لا تقبل سوى البيانات النصية. للبيانات الثنائية، استخدم QR Code مع QrEncodeMode.BYTE.

هل تتحقق المكتبة من طول البيانات لأكواد QR؟

QrInputParser يتحقق من أن البيانات تتناسب مع سعة الإصدار المطلوب من QR. إذا لم يتم تحديد إصدار، تختار المكتبة أصغر إصدار يمكنه استيعاب البيانات.

ملخص API Reference

انظر أيضاً

• Aspose.BarCode for Python — Enterprise Documentation