كيفية إضافة الباركود إلى PDF في Java

مقدمة

هل وجدت نفسك تتعامل مع مصداقية المستندات في تطبيق Java الخاص بك؟ لست وحدك. سواء كنت تبني نظام جرد، تدير العقود، أو تتعامل مع مستندات سلسلة الإمداد، فهناك احتمال كبير أنك تحتاج إلى طريقة موثوقة لتوقيع والتحقق من ملفات PDF تلقائيًا.

التوقيعات الرقمية التقليدية رائعة، لكن أحيانًا تحتاج إلى شيء أكثر تخصصًا—مثل توقيعات الباركود التي تعمل بسلاسة مع أنظمة المسح والعمليات الآلية. هنا يأتي دور باركودات GS1DotCode.

ما ستتعلمه:

  • كيفية توقيع مستندات PDF باستخدام باركودات GS1DotCode في Java
  • كيفية استخراج وحفظ صور توقيع الباركود
  • متى (ولماذا) تستخدم توقيعات الباركود بدلاً من الطرق التقليدية
  • الأخطاء الشائعة وكيفية تجنبها

بنهاية هذا الدليل، ستحصل على حل جاهز يمكنك دمجه في أي مشروع Java.

إجابات سريعة

  • ما المكتبة التي تضيف باركودات إلى ملفات PDF في Java؟ GroupDocs.Signature for Java.
  • ما صيغة الباركود التي يتم تغطيتها؟ GS1DotCode، مصفوفة نقطية ثنائية الأبعاد مدمجة.
  • هل أحتاج إلى ترخيص مدفوع؟ النسخة التجريبية المجانية تكفي للاختبار؛ الإنتاج يتطلب ترخيصًا تجاريًا.
  • هل يمكنني استخراج الباركود كصورة؟ نعم، باستخدام واجهة برمجة التطبيقات BarcodeSignature.
  • ما إصدار Java المطلوب؟ JDK 8 أو أعلى.

ما هو إضافة الباركود؟

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

لماذا نختار باركودات GS1DotCode؟

تم تصميم GS1DotCode للمواقف التي تكون فيها المساحة ضيقة. على عكس الباركودات الخطية التي تمتد أفقيًا، تُنشئ DotCode مصفوفة نقطية ثنائية الأبعاد تُحزم كمية هائلة من المعلومات في مساحة صغيرة. هذا يجعلها مثالية لـ:

  • ملصقات المنتجات الصغيرة حيث كل مليمتر مهم
  • الطباعة عالية السرعة على خطوط الإنتاج (الصيغة مُصممة لذلك)
  • تتبع سلسلة الإمداد حيث تحتاج إلى ترميز هياكل بيانات معقدة

يمكن للصيغة معالجة ما يصل إلى 3,116 حرفًا في مساحة مدمجة وتقرأ بثقة حتى بسرعات عالية أو مع تلف جزئي. إذا كنت تعمل في مجال التجزئة أو اللوجستيات، فمن المحتمل أن شركاؤك يستخدمون معايير GS1 بالفعل—وبالتالي تتحدث نفس اللغة.

نصيحة احترافية: استخدم GS1DotCode عندما تحتاج إلى تضمين أكثر من 20 حرفًا على ملصق أصغر من 1 بوصة × 1 بوصة.

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

قبل البدء بالبرمجة، تأكد من أن بيئتك تلبي المتطلبات التالية.

المكتبات والاعتمادات المطلوبة

  • GroupDocs.Signature for Java 23.12 أو أحدث (يدعم أكثر من 30 صيغة مستند)
  • Maven أو Gradle لإدارة الاعتمادات

إعداد البيئة

  • JDK 8 أو أحدث مثبت ومُعد في PATH الخاص بك
  • بيئة تطوير متكاملة مثل IntelliJ IDEA أو Eclipse أو NetBeans
  • ملف PDF تجريبي للتجربة (أي PDF غير محمي سيكفي)

المتطلبات المعرفية

  • أساسيات لغة Java (المتغيرات، الدوال، الكائنات)
  • الإلمام بإعلان الاعتمادات في Maven أو Gradle
  • فهم عمليات إدخال/إخراج الملفات في Java (مثل FileInputStream)

إذا كان أي من هذه العناصر مفقودًا، توقف وقم بتثبيتها الآن؛ الخطوات اللاحقة تفترض وجودها.

إعداد GroupDocs.Signature for Java

Maven

إذا كنت تستخدم Maven، أضف الاعتماد التالي إلى ملف pom.xml الخاص بك:

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

سيقوم Maven بتنزيل المكتبة وجميع الاعتمادات المتداخلة تلقائيًا.

Gradle

لمستخدمي Gradle، أدرج هذا السطر في ملف build.gradle الخاص بك:

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

يقوم Gradle بحل الحزمة بنفس الطريقة السهلة.

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

إذا كنت تفضل الإدارة اليدوية، قم بتحميل ملفات JAR من صفحة الإصدارات الرسمية: إصدارات GroupDocs.Signature for Java. ضع ملفات JAR في مسار classpath الخاص بالمشروع.

نصيحة احترافية: Maven أو Gradle يبسطان الترقيات المستقبلية—فقط قم بزيادة رقم الإصدار.

الحصول على الترخيص

تقدم GroupDocs ثلاث خيارات للترخيص:

  • نسخة تجريبية مجانية – لا تحتاج إلى بطاقة ائتمان، تُضاف علامات مائية إلى المخرجات
  • ترخيص مؤقت – تقييم كامل للميزات لمدة 30 يومًا
  • ترخيص تجاري – يزيل حدود التجربة ويمنح حقوق الإنتاج

بعد الحصول على ملف الترخيص، ضعّه في مجلد الموارد (resources) بالمشروع وحمّله قبل إنشاء أي كائن Signature.

License.setLicense يحمل ملف ترخيص GroupDocs، مما يتيح تشغيل كامل الميزات دون قيود التجربة.

شغّل المقتطف التالي للتحقق من تحميل المكتبة بشكل صحيح:

import com.groupdocs.signature.Signature;

public class InitializeGroupDocs {
    public static void main(String[] args) {
        // Create an instance of Signature
        Signature signature = new Signature("path/to/your/document.pdf");
        
        System.out.println("Initialization successful!");
    }
}

إذا رأيت “Initialization successful!” فإن الإعداد اكتمل. وإلا، تحقق مرة أخرى من classpath ومسار الترخيص.

دليل التنفيذ

سنغطي ميزتين أساسيتين: (1) توقيع PDF بباركود GS1DotCode و(2) استخراج ذلك الباركود كملف صورة.

الميزة 1: توقيع المستند بباركود GS1DotCode

كيف يمكن توقيع PDF بباركود GS1DotCode في Java؟

حمّل ملف PDF المستهدف باستخدام new Signature("source.pdf")، اضبط كائن BarcodeSignOptions يحتوي على بيانات بصيغة GS1، ثم استدعِ sign() لإنتاج PDF جديد يدمج الباركود. تقوم هذه العملية بكتابة الباركود مباشرةً في تدفق محتوى PDF، مما يحافظ عليه عبر الطباعة وإعادة المسح.

تتضمن العملية ثلاث خطوات مختصرة: إنشاء كائن Signature، إعداد BarcodeSignOptions، واستدعاء sign(). يوضح الكود أدناه كل خطوة.

1. تهيئة كائن التوقيع

فئة Signature هي نقطة الدخول لجميع عمليات معالجة المستندات في GroupDocs.Signature.

import com.groupdocs.signature.Signature;

String sourceFilePath = "YOUR_DOCUMENT_DIRECTORY/document.pdf";
final Signature signature = new Signature(sourceFilePath);

لماذا هذا مهم: كائن Signature يج abstracts التعامل مع الملفات، ويُجري تدفق ملفات PDF الكبيرة بكفاءة دون تحميل الملف بالكامل في الذاكرة.

2. ضبط خيارات الباركود

تتيح لك BarcodeSignOptions تحديد نوع الباركود، البيانات المشفرة، الموقع، والأبعاد.

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

BarcodeSignOptions gs1DotCodeOptions = new BarcodeSignOptions("(01)04912345123459(15)970331(30)128(10)ABC123", BarcodeTypes.GS1DotCode);
gs1DotCodeOptions.setLeft(100); // Set barcode position
gs1DotCodeOptions.setTop(100);
gs1DotCodeOptions.setHeight(150);
gs1DotCodeOptions.setWidth(200);

نقاط رئيسية:

  • السلسلة المشفرة تتبع معرفات التطبيقات (AIs) في GS1 مثل (01) لـ GTIN، (15) لتاريخ الانتهاء، إلخ.
  • setLeft() و setTop() تستخدم النقاط (72 pt = 1 in).
  • الحجم الموصى به للقراءة الموثوقة هو 108 pt × 108 pt (1.5 in × 1.5 in).
3. توقيع المستند

أضف الخيارات المضبوطة إلى قائمة (يمكنك دمج أنواع توقيع متعددة) ثم استدعِ sign().

import java.util.ArrayList;
import java.util.List;

List<com.groupdocs.signature.options.sign.SignOptions> listOptions = new ArrayList<>();
listOptions.add(gs1DotCodeOptions);
signature.sign("YOUR_OUTPUT_DIRECTORY/signed_document_with_gs1dotcode.pdf", listOptions);

ملاحظة أداء: إعادة استخدام كائن Signature واحد للعمليات الدفعية يقلل من تكلفة إنشاء الكائنات ويحسن معدل المعالجة.

الميزة 2: حفظ محتوى توقيع الباركود إلى ملف

كيف يمكن استخراج صورة باركود من PDF موقع في Java؟

يمثل BarcodeSignature كائن توقيع باركود يتم استخراجه من مستند موقع، ويوفر وصولًا إلى بياناته ومحتوى صورته.

أنشئ كائن BarcodeSignature (أو استخرج واحدًا عبر search())، اقرأ بيانات الصورة المشفرة بـ Base64 عبر getContent()، فك الترميز، واكتب البايتات إلى ملف PNG. ستحصل على صورة مستقلة يمكنك عرضها في واجهة المستخدم أو إرسالها إلى طابعة الملصقات.

1. محاكاة إنشاء توقيع باركود

في السيناريوهات الحقيقية ستحصل على BarcodeSignature من نتيجة بحث؛ هنا نقوم بإنشائه يدويًا للتوضيح.

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.io.FileOutputStream;

String base64String = "SampleBase64EncodedData";
BarcodeSignature barcodeSignature = new BarcodeSignature(base64String);
2. حفظ المحتوى إلى ملف

قم بفك ترميز سلسلة Base64 واكتب البايتات الناتجة إلى القرص باستخدام كتلة try‑with‑resources.

int imageNumber = 1;
String formatExtension = ".png";  // Assume PNG format

try (FileOutputStream outputStream = new FileOutputStream("YOUR_OUTPUT_DIRECTORY/barcode_image" + imageNumber + formatExtension)) {
    byte[] byteArray = barcodeSignature.getContent();
    if (byteArray != null) {
        outputStream.write(byteArray);
    }
}

تحذير: قد تُعيد getContent() قيمة null إذا تم إنشاء التوقيع دون تضمين صورة. تحقق دائمًا من عدم وجود null قبل الكتابة.

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

المشكلة: الباركود لا يُمسح

الأعراض: يبدو الباركود جيدًا في عارض PDF لكن الماسحات تُرجع أخطاء.

الحلول:

  • زد حجم الباركود إلى ما لا يقل عن 108 pt × 108 pt.
  • تأكد من أن دقة الطابعة ≥ 300 dpi.
  • تحقق من أن سلسلة بيانات GS1 تتبع بنية AI الصحيحة؛ فقدان قوس يُعطل الماسح.

المشكلة: OutOfMemoryError في ملفات PDF الكبيرة

الأعراض: معالجة مستندات أكبر من 50 MB تُسبب فشل مساحة الheap.

الحلول:

  • شغّل JVM بذاكرة heap أكبر، مثل -Xmx2g.
  • عالج المستندات على دفعات أصغر.
  • حرّر كائنات Signature صراحةً: signature.dispose() بعد كل ملف.

المشكلة: الباركود يظهر ضبابيًا

الأعراض: الباركود المرسوم يبدو بكسليًا في PDF الناتج.

الحلول:

  • استخدم أبعادًا أكبر؛ المكتبة تُرسم رسومات متجهية عندما يكون ذلك ممكنًا، لكن تقليل الحجم بعد الإنشاء يُدخل تشويهات.
  • تجنّب التحويل من raster إلى vector؛ دع GroupDocs يتعامل مع الرسم مباشرةً من التعريف المتجهي.

المشكلة: استثناءات الترخيص

الأعراض: أخطاء مثل “License not found” أو “Trial limitations exceeded”.

الحلول:

  • ضع ملف الترخيص في جذر classpath (src/main/resources).
  • استدعِ License.setLicense("GroupDocs.Signature.lic") قبل أي إنشاء كائن Signature.
  • بالنسبة للتراخيص المؤقتة، تأكد من تاريخ الانتهاء (30 يومًا من الإصدار).

متى نستخدم هذا النهج

حالات الاستخدام الجيدة

  • تتبع سلسلة الإمداد – تضمين معرفات المنتجات، أرقام الدفعات، وتواريخ الانتهاء مباشرةً على مستندات الشحن.
  • الطباعة الآلية للملصقات – توليد باركودات في الوقت الفعلي لكل فاتورة PDF.
  • الصناعات المنظمة – معايير GS1 إلزامية في العديد من قطاعات التجزئة والرعاية الصحية.

متى ن考虑 البدائل

  • إذا كنت تحتاج فقط إلى سلامة تشفيرية، فالتوقيع الرقمي القياسي PKI أكثر ملاءمة.
  • للتعليقات البصرية البسيطة، قد يكون توقيع نصي أو ختم صورة كافيًا.
  • عندما يكون حجم المستند قيودًا حاسمة، تجنّب إضافة صور باركود عالية الدقة؛ استخدم QR codes التي يمكن أن تكون أصغر لنفس كثافة البيانات.

ممارسات الأمان الموصى بها

التحقق من صحة البيانات

نقّح أي بيانات يقدمها المستخدم قبل ترميزها في الباركود. السلاسل غير الصالحة في GS1 قد تتسبب بأخطاء مسح لاحقة أو، في أسوأ الأحوال، تُحدث تجاوزات للذاكرة في برامج الماسحات القديمة.

التحكم في الوصول

طبق نظام التحكم بالوصول القائم على الأدوار (RBAC) بحيث لا يتمكن إلا المستخدمون المخولون من استدعاء واجهة التوقيع. احفظ ملف الترخيص بأمان وقم بتقييد أذونات نظام الملفات.

تسجيل التدقيق

سجّل كل عملية توقيع مع تفاصيل مثل معرف المستخدم، الطابع الزمني، مسار الملف المصدر، والحمولة الدقيقة لـ GS1. مثال على مقتطف تسجيل:

// Simple logging example (use a proper logging framework in production)
System.out.println("Document signed by: " + userId + " at " + new Date());
System.out.println("Barcode data: " + barcodeData);

كشف العبث

اجمع بين توقيع الباركود وتوقيع رقمي تشفيرى. يوفر الباركود بيانات قابلة للقراءة آليًا، بينما يضمن التوقيع الرقمي النزاهة وعدم الإنكار.

تطبيقات عملية

1. إدارة سلسلة الإمداد

يتلقى كل إيصال شحن باركود GS1DotCode يشفّر GTIN الشحنة، الدفعة، والوجهة. تقوم الماسحات عند كل نقطة تفتيش بتحديث نظام ERP تلقائيًا، مما يقلل أخطاء الإدخال اليدوي بنسبة 98 %.

2. التحكم بالمخزون

عند وصول البضائع، يُوقع ملف PDF الوارد بباركود يحتوي على رقم طلب الشراء وكميات الأصناف. يقوم موظفو المستودع بمسح الباركود، وتُحدّث قاعدة بيانات المخزون في الوقت الفعلي.

3. نقطة بيع التجزئة

تسمح الفواتير المطبوعة بباركود للباعة بمسح الفاتورة لمعالجة المرتجعات بدلاً من إدخال معرف المعاملة يدويًا، مما يقلل متوسط زمن الخروج 30 ثانية لكل عملية إرجاع.

4. وثائق الرعاية الصحية

تُوقع الوصفات الطبية بباركود GS1DotCode يضم معرف المريض، رمز الدواء، وتعليمات الجرعة. تقوم الصيدليات بمسح الباركود، مما يلغي أخطاء النسخ التي قد تؤدي إلى أحداث دوائية سلبية.

اعتبارات الأداء

إدارة الذاكرة

تقوم GroupDocs.Signature ببث بيانات PDF، لكن لا يزال من الضروري إغلاق الموارد بسرعة:

try (Signature signature = new Signature(sourceFilePath)) {
    // Do your signing operations here
} // Signature automatically disposed here

استخدام try‑with‑resources يضمن تحرير كائن Signature لمقابض الملفات حتى في حال حدوث استثناء.

نصائح المعالجة الدفعية

  • أعد استخدام نفس كائن BarcodeSignOptions عندما تكون الحمولة متطابقة عبر مستندات متعددة.
  • نفّذ التوازي باستخدام ExecutorService للعبء المعتمد على المعالج؛ خادم بثمانية أنوية يمكنه توقيع ≈ 150 PDF في الدقيقة عندما يكون كل ملف أقل من 5 MB.
  • قلل من استدعاءات التحقق من الترخيص الخارجي لتجنب حدود السرعة.

تحسين صيغة الملف

  • فضلًا عن PDF/A‑1b للأرشفة؛ يضغط التدفقات ويقلل حجم الملف حتى 40 %.
  • حافظ على أبعاد الباركود لا تزيد عن الحد الضروري؛ باركود بحجم 1.5 in × 1.5 in يضيف تقريبًا 15 KB إلى PDF حجمه 2 MB.

الخلاصة

أصبحت الآن تمتلك سير عمل كامل، جاهز للإنتاج، لإضافة توقيعات باركود GS1DotCode إلى ملفات PDF في Java، واستخراج تلك الباركودات كصور، ودمج العملية في خطوط أنابيب إدارة المستندات الأكبر. تذكر أن:

  1. تتحقق من صحة حمولة GS1 قبل الترميز.
  2. تختار أبعاد الباركود التي توازن بين موثوقية المسح ومتطلبات التخطيط.
  3. تجمع بين توقيعات الباركود والتوقيعات الرقمية للحصول على تغطية أمان شاملة.

الخطوات التالية: استكشف أنواع التوقيع الأخرى التي تقدمها GroupDocs.Signature—رموز QR، طوابع نصية، وشهادات رقمية—جميعها تشترك في واجهة برمجة تطبيقات موحدة.

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

س: ما هو GS1DotCode ولماذا يختلف عن رموز QR؟
ج: GS1DotCode هو مصفوفة نقطية ثنائية الأبعاد مدمجة تخزن حتى 3,116 حرفًا في مساحة أصغر من رموز QR، مما يجعلها مثالية للملصقات الصغيرة والطباعة عالية السرعة.

س: هل يمكنني استخدام النسخة التجريبية في بيئات الإنتاج؟
ج: النسخة التجريبية مخصصة للتقييم وتضيف علامة مائية إلى الملفات الناتجة. يتطلب الاستخدام الإنتاجي ترخيصًا مُشتَرًى أو ترخيصًا مؤقتًا لمدة 30 يومًا.

س: كيف يمكنني وضع الباركود على صفحة محددة؟
ج: اضبط setPageNumber(pageIndex) على كائن BarcodeSignOptions، ثم عدّل setLeft() و setTop() لتحديد الموقع بدقة.

س: هل يدعم GroupDocs.Signature ملفات PDF محمية بكلمة مرور؟
ج: نعم. قدم كلمة المرور عند إنشاء كائن Signature: new Signature("file.pdf", "password").

س: كيف يمكنني التحقق من أن توقيع الباركود أُضيف بشكل صحيح؟
Signature.search() يبحث في المستند عن توقيعات، ويُعيد مجموعة من كائنات التوقيع المطابقة. استخدم Signature.search() مع BarcodeSearchOptions. كائنات BarcodeSignature المرتجعة تحتوي على البيانات المشفرة ومحتوى الصورة للتحقق.

س: ما هو الحد الأدنى لحجم الباركود لضمان مسح موثوق؟
ج: استهدف حجمًا لا يقل عن 108 pt × 108 pt (1.5 in × 1.5 in). الأحجام الأكبر تحسّن القابلية للقراءة، خاصة على الطابعات منخفضة الدقة.

س: هل يمكنني توقيع عدة ملفات PDF في وقت واحد؟
ج: نعم. أنشئ مجموعة من الخيوط (thread pool) وأنشئ كائن Signature منفصل لكل خيط؛ المكتبة آمنة للاستخدام المتعدد عندما يعمل كل خيط على مستنده الخاص.

س: هل هناك حد لعدد الباركودات التي يمكن تضمينها في PDF واحد؟
ج: لا يوجد حد صريح، لكن كل باركود يضيف تقريبًا 15 KB من البيانات. بالنسبة للملفات التي تتجاوز 100 MB، يُفضَّل المعالجة الدفعية لإدارة استهلاك الذاكرة.

س: هل تعمل المكتبة على أنظمة غير Windows؟
ج: GroupDocs.Signature for Java مستقل عن النظام ويعمل على أي نظام تشغيل يدعم JRE متوافق، بما في ذلك Linux و macOS.

آخر تحديث: 2026-08-25
تم الاختبار مع: GroupDocs.Signature 23.12 for Java
المؤلف: GroupDocs

دروس ذات صلة