توقيع PDF باستخدام الباركود HIBC في Java

إذا كنت تقوم بتطوير برنامج لوجستيات الأدوية أو الرعاية الصحية، فمن المحتمل أن تكون قد واجهت مشكلة تتبع تعتمد على الورق، وفقدان التوقيعات، وكوابيس التدقيق. توقيع PDF باستخدام الباركود—وخاصةً HIBC Data Matrix أو QR code—يخلق أثرًا مقاومًا للعبث وقابلًا للقراءة آليًا يبقى بعد الطباعة والمسح والمراجعة التنظيمية. في هذا الدرس ستتعرف بالضبط على كيفية إضافة كل من Data Matrix و QR barcodes إلى ملف PDF باستخدام GroupDocs.Signature for Java.

إجابات سريعة

  • ما المكتبة التي تتعامل مع باركود HIBC في Java؟ GroupDocs.Signature for Java.
  • ما هو تنسيق الباركود الأكثر ضغطًا؟ Data Matrix – مثالي للملصقات الصغيرة.
  • هل يمكنني إضافة كل من QR و Data Matrix إلى نفس ملف PDF؟ Yes, just create separate QrCodeSignOptions.
  • هل أحتاج إلى اتصال بالإنترنت أثناء التشغيل؟ No, the library works fully offline after installation.
  • ما نسخة Java الموصى بها؟ Java 11+ for production‑grade performance.

ما هو توقيع PDF باستخدام باركود HIBC؟

Signature هي الفئة الأساسية في GroupDocs.Signature التي تمثل مستند PDF وتتيح تضمين التوقيعات الرقمية. توفر فئة Signature في GroupDocs.Signature for Java طرقًا لتضمين باركود HIBC كتوقيعات رقمية. من خلال توقيع PDF باستخدام باركود HIBC، تنشئ سجلًا قابلًا للتحقق ومقاومًا للعبث يمكن مسحه في أي مرحلة من سلسلة التوريد.

لماذا نستخدم Data Matrix و QR معًا؟

يوفر Data Matrix أصغر مساحة بينما لا يزال قادرًا على احتواء ما يصل إلى 2,335 حرفًا أبجديًا رقميًا، مما يجعله مثاليًا للمناطق المكتظة بالملصقات. من ناحية أخرى، تدعم رموز QR ما يصل إلى 4,296 حرفًا وتُقرأ عالميًا بواسطة الهواتف الذكية. الجمع بينهما يمنحك أفضل توازن بين كفاءة المساحة وسعة البيانات، مما يضمن أن جميع أصحاب المصلحة—من ماسحات المستودعات إلى التطبيقات المحمولة—يمكنهم قراءة المعلومات التي يحتاجونها.

المتطلبات المسبقة

  • JDK 11 أو أعلى (Java 8 يعمل لكن يُنصح بـ Java 11+ لأداء مثالي).
  • IDE مثل IntelliJ IDEA أو Eclipse أو VS Code مع امتدادات Java.
  • Maven أو Gradle لإدارة التبعيات (الأمثلة أدناه).
  • PDF تجريبي (مثل sample.pdf) لاختبار التنفيذ.
  • رخصة GroupDocs.Signature صالحة (تجربة مجانية للتطوير، رخصة مدفوعة للإنتاج).

إعداد GroupDocs.Signature للـ Java

تكوين Maven

أضف التبعية إلى ملف pom.xml الخاص بك:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

تكوين Gradle

للمشاريع التي تستخدم Gradle، أضف هذا إلى ملف build.gradle الخاص بك:

implementation 'com.groupdocs:groupdocs-signature:23.12'

خيار التحميل المباشر

يمكنك أيضًا تنزيل ملف JAR مباشرةً من GroupDocs.Signature for Java releases وإضافته إلى مسار الفئة (classpath) في مشروعك يدويًا. يعمل هذا النهج جيدًا في بيئات الشبكة المقيدة.

الحصول على رخصة

اطلب نسخة تجريبية مجانية أو رخصة مؤقتة من GroupDocs لإزالة العلامات المائية وإتاحة جميع الميزات. تتطلب عمليات النشر في الإنتاج رخصة مدفوعة.

التهيئة الأساسية

Signature هو نقطة الدخول لجميع عمليات التوقيع. يقوم بتحميل ملف PDF، وتطبيق الباركود، وكتابة الملف الموقّع.

import com.groupdocs.signature.Signature;

class InitializeSignature {
    public static void main(String[] args) {
        Signature signature = new Signature("sample.pdf");
        // Proceed with signing operations...
    }
}

كيفية إنشاء PDF بتنسيق Data Matrix مع باركود HIBC؟

قم بإنشاء كائن Signature مع ملف PDF المصدر الخاص بك، واضبط QrCodeSignOptions إلى تنسيق Data Matrix، وقدم سلسلة HIBC مُنسقة بشكل صحيح، ثم استدعِ sign(). تقوم المكتبة بكتابة ملف PDF الموقّع إلى الوجهة، مع الحفاظ على التخطيط وتضمين الباركود كتوقيع مقاوم للعبث.

QrCodeSignOptions يحدد نوع الباركود، المحتوى، الحجم، وموقع التوقيع.

  1. استيراد الفئات المطلوبة – هذه تمنحك الوصول إلى محرك التوقيع وخيارات Data Matrix.
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.QrCodeSignOptions;
import com.groupdocs.signature.domain.qrcodes.QrCodeTypes;
  1. إنشاء كائن Signature باستخدام مسارات مطلقة للملفات المصدر والوجهة.
String sourceFilePath = "YOUR_DOCUMENT_DIRECTORY";
String destinFilePath = "YOUR_OUTPUT_DIRECTORY/SignWithHIBCLICQR.pdf";

final Signature signature = new Signature(sourceFilePath);
  1. تهيئة خيارات Data Matrix – اضبط سلسلة HIBC، اختر QrCodeTypes.HIBCLICDataMatrix، وحدد إحداثيات الموضع. QrCodeTypes تُعدّد تنسيقات الباركود المدعومة لتوقيعات HIBC.
QrCodeSignOptions hibcLic_QR = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICQR);
hibcLic_QR.setLeft(1); // Set the position from left
hibcLic_QR.setTop(1);   // Set the position from top
hibcLic_QR.setReturnContent(true); // Return content after signing
hibcLic_QR.setReturnContentType(FileType.PNG); // Specify return content type as PNG
  1. تطبيق التوقيع على ملف PDF.
signature.sign(destinFilePath, hibcLic_QR);
  1. تحرير الموارد لتحرير مقابض الملفات وتجنب تسرب الذاكرة.
finally {
    if (signature != null) signature.dispose();
}

مثال عملي كامل

إليك التدفق الكامل في كتلة واحدة (الرموز النائبة تمثل الشيفرة الدقيقة التي ستلصقها من المقاطع السابقة):

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.QrCodeSignOptions;
import com.groupdocs.signature.domain.qrcodes.QrCodeTypes;

public class HibcQrSigning {
    public static void main(String[] args) {
        String sourceFilePath = "sample.pdf";
        String destinFilePath = "output/SignWithHIBCLICQR.pdf";
        
        Signature signature = null;
        try {
            signature = new Signature(sourceFilePath);
            
            QrCodeSignOptions hibcLic_QR = new QrCodeSignOptions(
                "A123PROD30917/75#422011907#GP293", 
                QrCodeTypes.HIBCLICQR
            );
            hibcLic_QR.setLeft(1);
            hibcLic_QR.setTop(1);
            hibcLic_QR.setReturnContent(true);
            hibcLic_QR.setReturnContentType(FileType.PNG);
            
            signature.sign(destinFilePath, hibcLic_QR);
            System.out.println("PDF signed successfully with HIBC QR code");
            
        } catch (Exception e) {
            System.err.println("Error signing PDF: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (signature != null) signature.dispose();
        }
    }
}

إجابة مباشرة (40–70 كلمة)

لـ إنشاء PDF بتنسيق Data Matrix، أنشئ كائن Signature مع ملف PDF المصدر الخاص بك، اضبط QrCodeSignOptions إلى QrCodeTypes.HIBCLICDataMatrix وقدم سلسلة HIBC مُنسقة بشكل صحيح، ثم استدعِ signature.sign(outputPath, options). تقوم المكتبة بكتابة ملف PDF الموقّع إلى الوجهة، مع الحفاظ على التخطيط وتضمين الباركود كتوقيع مقاوم للعبث.

كيفية إضافة QR code إلى PDF باستخدام GroupDocs.Signature؟

حمّل ملف PDF، قم بتكوين QrCodeSignOptions لتنسيق QR، واستدعِ sign(). تقوم المكتبة بتكبير صورة QR لتكون قابلة للقراءة وتضعها بناءً على الإحداثيات التي تحددها، متجنبة التداخل مع المحتوى الموجود. يضمن ذلك بقاء الباركود قابلًا للمسح بعد الطباعة ويتوافق مع معايير HIBC.

QrCodeSignOptions يحدد محتوى الباركود QR، حجمه، وموقعه.

  1. استيراد الفئات الخاصة بـ QR
QrCodeSignOptions hibcLic_AZ = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICAztec);
hibcLic_AZ.setLeft(1); // Set the position from left
hibcLic_AZ.setTop(200); // Set the position from top
hibcLic_AZ.setReturnContent(true); // Return content after signing
hibcLic_AZ.setReturnContentType(FileType.PNG); // Specify return content type as PNG
  1. إنشاء وتكوين خيارات QR – لاحظ استخدام QrCodeTypes.HIBCLICQR.
signature.sign(destinFilePath, hibcLic_AZ);
  1. توقيع المستند
QrCodeSignOptions hibcLic_DM = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICDataMatrix);
hibcLic_DM.setLeft(1); // Set the position from left
hibcLic_DM.setTop(400); // Set the position from top
hibcLic_DM.setReturnContent(true); // Return content after signing
hibcLic_DM.setReturnContentType(FileType.PNG); // Specify return content type as PNG

إجابة مباشرة: استخدم QrCodeTypes.HIBCLICQR في QrCodeSignOptions، اضبط سلسلة محتوى HIBC، وضع الكود باستخدام setLeft() و setTop()، ثم استدعِ signature.sign(outputPath, options). يتم تضمين باركود QR فورًا، جاهزًا للالتقاط عبر الهاتف الذكي أو الماسح.

الأخطاء الشائعة التي يجب تجنبها

1. نسيان تحرير الموارد

خطأ:

Signature signature = new Signature("sample.pdf");
signature.sign(destinFilePath, options);
// Oops, no dispose() call

تصحيح: غلف استخدام Signature داخل كتلة try‑with‑resources أو استدعِ close() صراحةً في جملة finally.

2. استخدام سلاسل HIBC غير صحيحة

خطأ: استخدام سلاسل عامة مثل “12345”.
تصحيح: اتبع معيار HIBCC (مثال: A123PROD30917/75#422011907#GP293). تحقق باستخدام HIBCC online validator.

3. ترميز مسارات الملفات صراحةً

خطأ:

String sourceFilePath = "C:/Users/John/Documents/test.pdf";

تصحيح: احفظ المسارات في ملف إعدادات أو متغير بيئي واقرأها أثناء التشغيل.

4. تجاهل تعارضات موضع الباركود

ضع الباركود بعيدًا عن النص أو التوقيعات الموجودة. استخدم إحداثيات PDF (الأصل في أسفل اليسار) واختبر باستخدام عينة مطبوعة.

5. عدم الاختبار باستخدام ماسحات حقيقية

اطبع ملف PDF الموقّع وامسحه باستخدام الجهاز الفعلي المستخدم في سير العمل الخاص بك. تحقق من قابلية القراءة بمختلف جودة الطباعة.

التطبيقات العملية في الرعاية الصحية

السيناريوالباركود الموصى بهلماذا يناسب
توزيع الأدويةQR Codeسعة بيانات عالية، يُمسح بسهولة بواسطة الهواتف الذكية.
إدارة المخزونData Matrixمساحة صغيرة، مثالي لملصقات الرفوف الكثيفة.
الامتثال التنظيمي (FDA 21 CFR Part 11)QR + Data Matrixالتنسيق المزدوج يوفر redundancy وauditability.
تتبع الأجهزة الطبيةAztec Codeالحجم الصغير يعمل على عبوات ذات مساحة محدودة.

اعتبارات الأداء وأفضل الممارسات

نمط المعالجة الدفعية

List<String> filesToSign = getFileList();
for (String filePath : filesToSign) {
    Signature signature = null;
    try {
        signature = new Signature(filePath);
        // Sign and save
    } finally {
        if (signature != null) signature.dispose();
    }
}
  • إنشاء كائن Signature جديد لكل ملف للحفاظ على استهلاك الذاكرة منخفضًا.
  • استخدم مجموعة خيوط ثابتة (Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors() - 1)) للمعالجة المتوازية، لكن راقب حجم الـ heap لأن كل Signature يحتفظ بملف PDF كامل في الذاكرة.

الحفاظ على تحديث المكتبات

إصدارات GroupDocs تحسن سرعة المعالجة بما يصل إلى 20 % وتضيف ميزات توافق HIBC جديدة. جدولة فحص التبعيات كل ثلاثة أشهر.

تخزين القوالب مؤقتًا

حمّل قالب PDF مرة واحدة، استنسخه لكل نوع باركود، ووقع النسخ. يقلل ذلك من عمليات I/O ويسرّع سير العمل عالي الحجم.

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

س: هل يمكن لـ GroupDocs.Signature توقيع أنواع ملفات غير PDF؟
ج: نعم، يدعم أيضًا DOCX و XLSX و PPTX و PNG و JPEG و TIFF باستخدام نفس واجهة برمجة تطبيقات توقيع الباركود.

س: كيف أحل أخطاء “Invalid barcode content”؟
ج: تأكد من أن سلسلة HIBC تتبع الصياغة الدقيقة لمعيار HIBCC، استخدم أداة التحقق عبر الإنترنت، وتأكد من استخدام الثابت QrCodeTypes المناسب للتنسيق المختار.

س: ما هي السعة القصوى للبيانات لكل تنسيق HIBC؟
ج: QR ≈ 4,296 حرفًا أبجديًا رقميًا، Aztec ≈ 3,832 رقمي / 3,067 أبجديًا رقميًا، Data Matrix ≈ 3,116 رقمي / 2,335 أبجديًا رقميًا. حافظ على أن تكون الرموز أقل من 200 حرف لضمان موثوقية المسح المثلى.

س: هل يمكن تضمين أنواع متعددة من الباركود في ملف PDF واحد؟
ج: بالتأكيد. أنشئ كائنات QrCodeSignOptions منفصلة بمواقع مختلفة واستدعِ signature.sign() لكل منها. فقط تأكد من عدم تداخلها.

س: هل أحتاج إلى اتصال بالإنترنت للتوقيع أثناء التشغيل؟
ج: لا. بعد وضع ملف JAR في classpath وتفعيل الرخصة، تُجرى جميع العمليات محليًا.

موارد إضافية

آخر تحديث: 2026-09-15
تم الاختبار مع: GroupDocs.Signature 23.12 للـ Java
المؤلف: GroupDocs

دروس ذات صلة