كيفية قراءة ملف PDF يحتوي على رمز QR باستخدام Java
المقدمة
هل احتجت يومًا لاستخراج معلومات الباركود من مئات فواتير PDF أو ملصقات الشحن أو مستندات الجرد؟ إن مسح الصفحات يدويًا أمر ممل وعرضة للأخطاء. سواءً كنت تبني نظام معالجة مستندات آلي أو تتحقق من أصالة المنتج، فإن العثور على الباركود بفعالية في ملفات PDF يمكن أن يكون تحديًا.
في هذا الدليل، ستتعلم كيفية قراءة ملف PDF يحتوي على رمز QR بفعالية باستخدام GroupDocs.Signature API. هذه الواجهة القوية تحول ما قد يستغرق ساعات من العمل اليدوي إلى بضع أسطر من الشيفرة فقط. يمكنك مسح المستندات بالكامل، وتحديد أنواع الباركود المحددة (مثل رموز QR أو Code128)، واستخراج بياناتها تلقائيًا.
ما ستتعلمه:
- إعداد GroupDocs.Signature للـ Java في دقائق
- البحث عن توقيعات الباركود داخل مستندات PDF
- تكوين خيارات البحث للحصول على نتائج دقيقة ومحددة
- التعامل مع أنواع مختلفة من الباركود (رموز QR، EAN، Code128، إلخ)
- استكشاف المشكلات الشائعة وتحسين الأداء
هيا نبدأ!
إجابات سريعة
- هل يمكن لـ GroupDocs.Signature قراءة رموز QR من ملفات PDF؟ نعم، فهو يكتشف QR، Data Matrix، PDF417، والعديد من الباركودات أحادية الأبعاد.
- هل أحتاج إلى ترخيص للاستخدام في الإنتاج؟ الترخيص التجاري مطلوب؛ يتوفر نسخة تجريبية مجانية للتقييم.
- ما نسخة Java المطلوبة؟ Java 8+ (يوصى بـ Java 11+).
- كيف أقصر البحث على صفحات محددة؟ استخدم
BarcodeSearchOptions.setAllPages(false)وحددsetPageNumber(). - هل الـ API آمن للاستخدام المتعدد الخيوط لمعالجة الدفعات؟ نعم، عند إنشاء كائن
Signatureمنفصل لكل خيط.
لماذا نبحث عن الباركود في ملفات PDF؟
قبل الخوض في التفاصيل التقنية، إليك لماذا هذا مهم في التطبيقات الواقعية:
سيناريوهات أعمال شائعة
- معالجة الفواتير – استخراج أرقام الطلبات أو رموز التتبع تلقائيًا من فواتير الموردين.
- إدارة المخزون – مسح كتالوجات المنتجات واستخراج باركودات SKU لتحديث قاعدة البيانات.
- الشحن واللوجستيات – التحقق من رموز تتبع الطرود في قوائم الشحن.
- توثيق المستندات – التحقق من صحة المستندات الموقعة عبر فحص الباركودات الأمنية المدمجة.
- السجلات الصحية – استخراج معرفات المرضى أو رموز الوصفات من المستندات الطبية.
تتعامل GroupDocs.Signature مع الجزء الصعب — لا تحتاج للقلق بشأن معالجة الصور، خوارزميات فك تشفير الباركود، أو تعقيدات عرض PDF. كل ذلك مدمج.
المتطلبات المسبقة
قبل بدء هذا البرنامج التعليمي، تأكد من توفر ما يلي:
المكتبات والاعتمادات المطلوبة
ستحتاج إلى إضافة مكتبة GroupDocs.Signature إلى مشروع Java الخاص بك. إليك طريقة الإضافة باستخدام Maven أو Gradle:
Maven:
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-signature</artifactId>
<version>23.12</version>
</dependency>
Gradle:
implementation 'com.groupdocs:groupdocs-signature:23.12'
ملاحظة: تحقق دائمًا من أحدث نسخة على GroupDocs.Signature for Java releases. استخدام أحدث نسخة يضمن حصولك على إصلاحات الأخطاء والميزات الجديدة.
إعداد البيئة
- JDK 8 أو أعلى – يتطلب GroupDocs.Signature Java 8 كحد أدنى (يوصى بـ Java 11+ لأداء أفضل).
- IDE – أي محرر نصوص يعمل، لكن IntelliJ IDEA أو Eclipse سيجعلان عملك أسهل مع الإكمال التلقائي وتصحيح الأخطاء.
- مستند PDF – احرص على وجود ملف PDF تجريبي يحتوي على باركودات (الفواتير، ملصقات الشحن، أو كتالوجات المنتجات مناسبة).
المتطلبات المعرفية
يجب أن تكون مرتاحًا مع:
- أساسيات صياغة Java ومفاهيم البرمجة الكائنية
- التعامل مع الاستثناءات باستخدام كتل
try‑catch - العمل مع المكتبات الخارجية في بيئة التطوير الخاصة بك
إذا كنت جديدًا على مكتبات Java الطرفية، لا تقلق — سنمر بكل خطوة خطوة.
إعداد GroupDocs.Signature للـ Java
البدء مع GroupDocs.Signature يستغرق بضع دقائق فقط. إليك عملية الإعداد الكاملة:
الخطوة 1: إضافة الاعتماد
استخدم Maven أو Gradle لتضمين المكتبة (انظر الشيفرة أعلاه). بعد إضافة الاعتماد، قم بتحديث مشروعك لتحميل ملفات JAR.
الخطوة 2: الحصول على الترخيص
تقدم GroupDocs عدة خيارات للترخيص:
- نسخة تجريبية مجانية – مثالية للاختبار. حمّلها من GroupDocs releases.
- ترخيص مؤقت – احصل على وصول كامل لمدة 30 يومًا عبر Temporary License Page.
- ترخيص تجاري – للاستخدام في الإنتاج، اشترِ ترخيصًا من GroupDocs Purchase.
نصيحة احترافية: ابدأ بالنسخة التجريبية لبناء نموذج إثبات المفهوم، ثم قم بالترقية إذا كان الـ API يلبي احتياجاتك.
الخطوة 3: التهيئة الأساسية
إليك كيفية إنشاء كائن Signature للعمل مع ملف PDF الخاص بك:
import com.groupdocs.signature.Signature;
String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with your PDF path
Signature signature = new Signature(filePath);
فئة Signature هي نقطة الدخول الرئيسية. تقوم بتحميل PDF إلى الذاكرة وتوفر طرقًا للبحث، التحقق، واستخراج بيانات التوقيع (بما في ذلك الباركودات).
مهم: تأكد من صحة مسار الملف وأن ملف PDF موجود. خطأ المبتدئين الشائع؟ استخدام الشرطات المائلة العكسية في Windows دون هروبها (C:\\Documents\\file.pdf وليس C:\Documents\file.pdf).
دليل التنفيذ
الآن الجزء الممتع — لنكتب الشيفرة للبحث عن الباركودات في ملف PDF الخاص بك.
البحث عن توقيعات الباركود في مستند
يظهر لك هذا القسم كيفية مسح PDF وتحديد جميع توقيعات الباركود. سنقسم العملية إلى خطوات قابلة للهضم مع شرح لكل جزء.
الخطوة 1: تهيئة كائن Signature
ابدأ بتحميل مستند PDF الخاص بك:
import com.groupdocs.signature.Signature;
String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with actual file path
Signature signature = new Signature(filePath);
ما يحدث هنا
فئة Signature تفتح ملف PDF وتجهزه للمعالجة. فكر فيها كفتح ملف في محرر نصوص — تقوم بتحميل المستند إلى الذاكرة لتتمكن من العمل عليه.
ملاحظة من الواقع
إذا كنت تعالج ملفات PDF من تحميلات المستخدمين، تحقق دائمًا من مسار الملف وتأكد من وجوده قبل إنشاء كائن Signature. هذا يمنع الأخطاء الغامضة لاحقًا.
الخطوة 2: إنشاء BarcodeSearchOptions
قم بتكوين طريقة البحث عن الباركودات:
import com.groupdocs.signature.options.search.BarcodeSearchOptions;
// Configure options for searching barcodes
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(true); // Search every page in the document
خيارات التكوين الرئيسية
setAllPages(true): يمسح جميع الصفحات. اضبطه علىfalseإذا كنت تريد فحص صفحات محددة فقط (قم بالتهيئة عبرsetPageNumber()).- لماذا هذا مهم: إذا كنت تعالج فواتير يكون فيها الباركود دائمًا في الصفحة 1، فإن مسح جميع الصفحات يضيع الموارد. بالنسبة لقوائم الشحن متعددة الصفحات، ستحتاج إلى
setAllPages(true).
نصيحة احترافية: يمكنك أيضًا تصفية النتائج حسب نوع الباركود (انظر قسم أنواع الباركود المدعومة أدناه). هذا يسرّع عمليات البحث عندما تعرف بالضبط الصيغة التي تبحث عنها.
الخطوة 3: تنفيذ البحث ومعالجة النتائج
الآن شغّل البحث وعالج النتائج:
import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.util.List;
try {
// Execute the barcode search
List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
// Check if any barcodes were found
if (signatures.isEmpty()) {
System.out.println("No barcode signatures found in the document.");
} else {
System.out.println("Found " + signatures.size() + " barcode signature(s):\n");
// Loop through each barcode and display details
for (BarcodeSignature barcodeSignature : signatures) {
System.out.println("----------------------------------------");
System.out.println("Barcode Type: " + barcodeSignature.getEncodeType().getTypeName());
System.out.println("Barcode Text: " + barcodeSignature.getText());
System.out.println("Page Number: " + barcodeSignature.getPageNumber());
System.out.println("Position: X=" + barcodeSignature.getLeft() +
", Y=" + barcodeSignature.getTop());
System.out.println("Size: Width=" + barcodeSignature.getWidth() +
", Height=" + barcodeSignature.getHeight());
System.out.println("----------------------------------------\n");
}
}
} catch (Exception e) {
System.err.println("Error searching for barcodes: " + e.getMessage());
e.printStackTrace();
} finally {
// Always dispose of the signature object to free resources
if (signature != null) {
signature.dispose();
}
}
ما يحدث في هذه الشيفرة
- تنفيذ البحث –
signature.search()يمسح PDF ويعيد قائمة من كائناتBarcodeSignature. - التحقق من الفارغ – يتأكد من وجود باركودات فعلًا (لتجنب استثناءات الـ null).
- استخراج البيانات – لكل باركود، نستخرج:
- النوع – صيغة الباركود (QR Code، Code128، EAN13، إلخ)
- النص – البيانات المفكوكة (رقم الطلب، رمز التتبع، SKU، إلخ)
- الموقع – رقم الصفحة وإحداثيات X/Y
- الأبعاد – العرض والارتفاع (مفيد للتحقق)
- معالجة الأخطاء – كتلة
try‑catchتمنع الانهيارات إذا حدث شيء غير متوقع (PDF تالف، ملف مفقود، إلخ). - تنظيف الموارد – كتلة
finallyتضمن تحرير كائنSignatureبشكل صحيح، مما يحرر الذاكرة.
تطبيق من الواقع
لنفترض أنك تعالج ملصقات شحن. ستستخرج قيمة getText() (رقم التتبع) وتخزنها في قاعدة البيانات. رقم الصفحة يخبرك أي ملصق يت对应 لأي شحنة إذا كنت تعالج مستندات مجمعة.
تصفية حسب نوع الباركود
يمكنك تسريع البحث بتحديد نوع الباركود المطلوب:
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setEncodeType(BarcodeTypes.QR); // Only search for QR codes
options.setAllPages(true);
متى تصفي
إذا كنت تعلم أن فواتيرك تحتوي فقط على باركودات Code128، فإن التصفية حسب النوع تقلل زمن المعالجة بنسبة 30‑50 % في المستندات الكبيرة.
أنواع الباركود المدعومة
يمكن لـ GroupDocs.Signature اكتشاف مجموعة واسعة من صيغ الباركود. إليك ما يمكنك البحث عنه:
باركودات 1D (خطية)
- Code128 – شائع في الشحن والتعبئة
- Code39 – يستخدم في صناعات السيارات والدفاع
- EAN13/EAN8 – باركودات منتجات التجزئة (تراها على كل منتج)
- UPC‑A/UPC‑E – معيار التجزئة في أمريكا الشمالية
- Interleaved2of5 – المستودعات والتوزيع
باركودات 2D (مصفوفية)
- QR Code – الأكثر شيوعًا — يُستخدم للروابط، كلمات مرور Wi‑Fi، معلومات الدفع
- Data Matrix – صيغة مدمجة للعناصر الصغيرة (مكونات إلكترونية)
- PDF417 – بطاقات الهوية الحكومية، بطاقات الصعود، رخص القيادة
- Aztec Code – تذاكر النقل
التصفية حسب النوع (المثال المعروض سابقًا) تساعدك على التركيز على الصيغة الدقيقة التي تحتاجها.
حالات الاستخدام الواقعية
إليك كيف يستخدم المطورون البحث عن الباركود في الإنتاج:
1. معالجة الفواتير تلقائيًا
السيناريو – يتلقى قسم المحاسبة أكثر من 500 فاتورة من الموردين يوميًا بصيغة PDF.
الحل – مسح كل PDF بحثًا عن باركودات Code39 تحتوي على أرقام الفواتير، ومطابقتها تلقائيًا مع أوامر الشراء في نظام ERP. هذا يلغي الإدخال اليدوي للبيانات ويقلل الأخطاء.
// Pseudo-code workflow
for (PDF invoice : invoiceBatch) {
List<BarcodeSignature> barcodes = searchBarcodes(invoice);
String invoiceNumber = barcodes.get(0).getText();
updateERPSystem(invoiceNumber, invoice);
}
2. تحديث مخزون المستودعات
السيناريو – يتلقى المستودع شحنات مع قوائم تعبئة PDF تحتوي على باركودات SKU بصيغة EAN13.
الحل – استخراج جميع الباركودات من قوائم التعبئة، وتحديث كميات المخزون تلقائيًا، وإشارة إلى أي تناقض للمراجعة.
3. توثيق المستندات
السيناريو – تتضمن المستندات القانونية رموز QR مع توقيعات تشفير للتحقق من الأصالة.
الحل – البحث عن رموز QR في العقود الموقعة، فك تشفير بيانات التوقيع، والتحقق منها مقابل سلطة شهادات موثوقة. هذا يضمن عدم تعديل المستندات.
4. إدارة السجلات الصحية
السيناريو – تحتوي ملفات المرضى في المستشفيات على تقارير مختبرية PDF مع باركودات Code128 لمعرفات العينات.
الحل – استخراج معرفات العينات تلقائيًا وربط نتائج المختبر بسجلات المرضى في نظام معلومات المستشفى (HIS).
المشكلات الشائعة والحلول
إليك مشاكل قد تواجهها وكيفية إصلاحها:
المشكلة 1: “لم يتم العثور على أي باركود” (مع علمك بوجوده)
الأسباب المحتملة
- جودة صورة الباركود منخفضة (ضبابية، بكسل)
- PDF مبني على صورة لكن الباركود صغير جدًا
- البحث عن نوع باركود غير صحيح
الحلول
- تحقق من دقة الصورة – تحتاج الباركودات على الأقل 200 DPI لاكتشاف موثوق. إذا كنت تمسح المستندات، استخدم 300 DPI أو أعلى.
- أزل تصفية النوع – جرّب البحث عن جميع أنواع الباركود أولًا (لا تضبط
setEncodeType())، ثم قلّص النطاق بعد تحديد ما هو موجود في المستند. - تحقق من جودة الباركود – افتح PDF في Adobe Acrobat وقم بالتكبير. إذا كان الباركود غير واضح لك، فسيصعب على الـ API أيضًا.
المشكلة 2: OutOfMemoryError مع ملفات PDF الكبيرة
السبب – تحميل PDF مكوّن من 500 صفحة بصور عالية الدقة يستهلك ذاكرة كبيرة.
الحل
- معالجة الصفحات على دفعات – بدلاً من
setAllPages(true), عالج 50 صفحة في كل مرة:
for (int startPage = 1; startPage <= totalPages; startPage += 50) {
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setPageNumber(startPage);
options.setPagesSetup(new PagesSetup());
options.getPagesSetup().setLastPage(Math.min(startPage + 49, totalPages));
List<BarcodeSignature> batchResults = signature.search(BarcodeSignature.class, options);
// Process results...
}
- زيادة حجم Heap للـ JVM – أضف
-Xmx4gإلى أمر تشغيل Java لتخصيص 4 GB من الذاكرة (عدل حسب الحاجة).
المشكلة 3: بطء الأداء على المستندات متعددة الصفحات
السبب – البحث في جميع الصفحات تسلسليًا يستغرق وقتًا، خاصةً مع الباركودات المعقدة مثل PDF417.
الحلول
- المعالجة المتوازية – إذا كانت الباركودات دائمًا في صفحات محددة (مثل الصفحة 1 للفواتير)، ابحث فقط في تلك الصفحات.
- تخزين النتائج مؤقتًا – إذا كنت تعالج نفس المستند عدة مرات، احفظ بيانات الباركود لتجنب إعادة الفحص.
- استخدام SSD – سرعة الإدخال/الإخراج مهمة عند تحميل ملفات PDF الكبيرة. SSD يقلل وقت التحميل بنسبة 60‑70 % مقارنةً بـ HDD.
المشكلة 4: نتائج إيجابية زائفة (التعرف على أنماط عشوائية كباركود)
السبب – الجداول أو الشبكات أو الخطوط قد تُخطئ كباركود.
الحل – تحقق من النتائج بفحص طول النص المفكك وتنسيقه:
for (BarcodeSignature barcode : signatures) {
String text = barcode.getText();
// Example: Invoice numbers are always 10 digits
if (text.matches("\\d{10}")) {
// Valid invoice number
processBarcode(barcode);
} else {
System.out.println("Skipping invalid barcode: " + text);
}
}
نصائح الأداء للمستندات الكبيرة
هل تعالج آلاف ملفات PDF؟ إليك كيفية تحسين العملية:
1. استراتيجية معالجة الدفعات
بدلاً من معالجة الملفات واحدةً تلو الأخرى، استخدم مجموعة خيوط لمعالجة عدة PDF في وقت واحد:
ExecutorService executor = Executors.newFixedThreadPool(4); // 4 parallel threads
for (String pdfPath : pdfFiles) {
executor.submit(() -> {
try (Signature sig = new Signature(pdfPath)) {
List<BarcodeSignature> results = sig.search(BarcodeSignature.class, options);
// Process results...
} catch (Exception e) {
e.printStackTrace();
}
});
}
executor.shutdown();
executor.awaitTermination(1, TimeUnit.HOURS);
تحسين الأداء – معالجة 1 000 ملف ينخفض من ~ساعتين إلى ~30 دقيقة على جهاز رباعي النوى.
2. تقليل نطاق البحث
إذا سمحت منطقية عملك، حدّد مساحة البحث:
// Only search the top‑right corner where barcodes are typically placed
options.setRectangle(new Rectangle(400, 50, 150, 150)); // X, Y, Width, Height
تحسين الأداء – أسرع بنسبة 40‑60 % في المستندات التي تكون فيها مواقع الباركود ثابتة.
3. مراقبة استهلاك الذاكرة
لعمليات الدفعات الطويلة، راقب حجم الـ heap واقترح جمع القمامة صراحة إذا لزم الأمر:
Runtime runtime = Runtime.getRuntime();
long usedMemory = runtime.totalMemory() - runtime.freeMemory();
if (usedMemory > (runtime.maxMemory() * 0.8)) {
System.gc(); // Suggest garbage collection
}
أفضل الممارسات
اتبع هذه الإرشادات لكتابة شفرة جاهزة للإنتاج:
1. دائمًا حرّر كائنات Signature
غلف الشيفرة باستخدام try‑with‑resources (Java 7+) لإغلاق الموارد تلقائيًا:
try (Signature signature = new Signature(filePath)) {
// Your search code here...
} // Automatically disposed
2. تحقق من صحة ملفات الإدخال
قبل المعالجة، تأكد من وجود الملف وأنه PDF صالح:
File pdfFile = new File(filePath);
if (!pdfFile.exists() || !pdfFile.canRead()) {
throw new FileNotFoundException("PDF not found or not readable: " + filePath);
}
// Optional: Verify it's actually a PDF (check magic bytes)
3. سجّل نتائج اكتشاف الباركود
للتصحيح والتدقيق، سجّل ما تم العثور عليه:
Logger logger = Logger.getLogger(BarcodeSearcher.class.getName());
for (BarcodeSignature barcode : signatures) {
logger.info(String.format("Detected %s barcode '%s' on page %d at (%.2f, %.2f)",
barcode.getEncodeType().getTypeName(),
barcode.getText(),
barcode.getPageNumber(),
barcode.getLeft(),
barcode.getTop()));
}
4. تعامل مع صيغ باركود مختلفة
تستخدم الصناعات صيغًا مختلفة. اجعل شيفرتك مرنة:
switch (barcode.getEncodeType().getTypeName()) {
case "QR":
// QR codes might contain URLs or JSON data
processQRCode(barcode.getText());
break;
case "Code128":
// Code128 typically contains alphanumeric order/tracking numbers
processTrackingNumber(barcode.getText());
break;
default:
logger.warning("Unexpected barcode type: " + barcode.getEncodeType());
}
5. اختبر باستخدام مستندات واقعية
لا تختبر فقط باستخدام ملفات PDF مثالية. استخدم مستندات فعلية من بيئة الإنتاج:
- فواتير ممسوحة ببقع القهوة
- ملصقات شحن مُرسلة بالفاكس مع ضوضاء
- صور هاتف محمول منخفضة الدقة محوّلة إلى PDF
هذا يكشف عن حالات حافة لا تظهر في العروض التجريبية.
الأسئلة المتكررة
س: هل يمكنني قراءة ملفات PDF التي تحتوي على رمز QR بدون ترخيص؟
ج: النسخة التجريبية المجانية تسمح بقراءة ملفات PDF التي تحتوي على رمز QR للتقييم، لكن الترخيص التجاري مطلوب للنشر في بيئات الإنتاج.
س: هل يدعم الـ API ملفات PDF المحمية بكلمة مرور؟
ج: نعم. يمكنك تمرير كلمة المرور عند إنشاء كائن Signature: new Signature(filePath, "password").
س: كيف أحسن الكشف في المسحات منخفضة الدقة؟
ج: زد DPI للمسح الأصلي (الحد الأدنى 200 DPI) وفكر في تصفية النوع لتقليل الإيجابيات الزائفة.
س: هل البحث آمن للاستخدام المتعدد الخيوط للمعالجة المتوازية؟
ج: يجب على كل خيط استخدام كائن Signature خاص به. الـ API نفسه آمن عند الاستخدام بهذه الطريقة.
س: أي نسخة من GroupDocs.Signature تم اختبارها مع هذا البرنامج التعليمي؟
ج: تم التحقق من الشيفرة مع GroupDocs.Signature 23.12.
الخلاصة
لقد تعلمت الآن كيفية قراءة ملف PDF يحتوي على رمز QR باستخدام Java وGroupDocs.Signature API. إليك ما غطيناه:
✅ الإعداد – إضافة GroupDocs.Signature إلى مشروعك وخيارات الترخيص
✅ التنفيذ – شيفرة كاملة للبحث، استخراج، ومعالجة بيانات الباركود
✅ أنواع الباركود – فهم الصيغ المدعومة (1D و2D)
✅ حالات الاستخدام الواقعية – معالجة الفواتير، إدارة المخزون، توثيق المستندات، السجلات الصحية
✅ استكشاف الأخطاء – حل المشكلات الشائعة مثل أخطاء الذاكرة والإيجابيات الزائفة
✅ الأداء – تحسين البحث لمعالجة كميات كبيرة من المستندات
يتولى GroupDocs.Signature تعقيدات تحليل PDF واكتشاف الباركود، مما يتيح لك التركيز على بناء منطق عملك. سواء كنت تُ automatisé معالجة الفواتير، تتحقق من ملصقات الشحن، أو تستخرج بيانات المخزون، لديك الآن حلًا قويًا.
آخر تحديث: 2026-03-01
تم الاختبار مع: GroupDocs.Signature 23.12
المؤلف: GroupDocs