كيفية إنشاء توقيع الباركود Java لمستندات PDF

مقدمة

في هذا البرنامج التعليمي ستتعلم كيفية create barcode signature Java لملفات PDF باستخدام GroupDocs.Signature. سواء كنت بحاجة إلى تضمين رموز المنتجات، أو معرفات التدقيق، أو أي بيانات منظمة في عقد، فإن توقيعات الباركود تسمح لك بإضافة معلومات قابلة للقراءة آليًا يمكن مسحها ضوئيًا على الفور مع الحفاظ على أمان المستند تشفيرياً. سنستعرض الإعداد، الكود، التخصيص، ونصائح أفضل الممارسات حتى تتمكن من البدء في إضافة توقيعات الباركود إلى ملفات PDF الخاصة بك في دقائق.

إجابات سريعة

  • ما المكتبة التي تضيف توقيعات الباركود في Java؟ GroupDocs.Signature for Java.
  • ما نوع الباركود الأفضل للتجزئة؟ GS1CompositeBar (industry‑standard for product tracking).
  • هل أحتاج إلى ترخيص للإنتاج؟ نعم – يلزم ترخيص GroupDocs مُشتَرٍ.
  • هل يمكنني إضافة كل من التوقيعات الرقمية وتوقيعات الباركود؟ بالطبع؛ اجمعهما للأمان وإمكانية المسح.
  • هل الكود متوافق مع Java 11 وما بعده؟ نعم، الـ API يعمل مع JDK 8+.

ما هو create barcode signature java؟

create barcode signature java يشير إلى عملية تضمين باركود في ملف PDF برمجيًا باستخدام كود Java. توفر GroupDocs.Signature API بسيط يولد صورة الباركود، يضعها على الصفحة، ويحفظ المستند الموقّع في عملية واحدة سلسة.

لماذا تستخدم توقيعات الباركود؟

توفر توقيعات الباركود بيانات وصفية قابلة للقراءة آليًا داخل PDF موقّع قانونيًا. تتيح التحقق البصري الفوري، وتبسط مسح سلسلة التوريد، وتسمح للأنظمة اللاحقة باستخراج البيانات المنظمة دون فتح الملف. يتم دعم أكثر من 60 تنسيق باركود، ويمكن لـ GS1CompositeBar ترميز معرفات المنتجات، الأرقام التسلسلية، ورموز الدفعات في رمز واحد مدمج—مثالي للتجزئة، الرعاية الصحية، والمالية.

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

  • Java Development Kit: JDK 8 أو أحدث (Java 11، 17، 21 كلها تعمل).
  • أداة البناء: Maven أو Gradle – اختر ما تفضله.
  • IDE: IntelliJ IDEA، Eclipse، أو VS Code.
  • مكتبة GroupDocs.Signature: أضف الاعتماد كما هو موضح أدناه.
  • الترخيص: تجربة مجانية للتطوير؛ ترخيص مُشتَرٍ للإنتاج.

إضافة GroupDocs.Signature إلى مشروعك

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

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

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

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

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

كيف تقوم بإعداد GroupDocs.Signature في Java؟

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

import com.groupdocs.signature.Signature;

// Point to your PDF file
Signature signature = new Signature("path/to/your/document.pdf");

مهم: يجب دائمًا تحرير كائن Signature بعد الاستخدام—هذا يحرّر مقابض الملفات ويحرّر الذاكرة.

كيف تقوم بتكوين خيارات توقيع الباركود؟

تُعرّف الفئة BarcodeSignOptions كل جانب من جوانب الباركود الذي ستضمّنه، من حمولة البيانات إلى النمط البصري. تعمل كحاوية لجميع إعدادات الباركود مثل النوع، الحجم، الألوان، والموقع. أدناه تكوين بسيط ينشئ باركود GS1CompositeBar يحتوي على GTIN ورقم تسلسلي، كما يوضح كيفية ضبط الهوامش وألوان الخلفية لقراءة مثالية.

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

// Create barcode with GS1 format data
BarcodeSignOptions options = new BarcodeSignOptions("(01)03212345678906/(21)A1B2C3D4E5F6G7H8");
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

السلسلة "(01)03212345678906/(21)A1B2C3D4E5F6G7H8" تتبع معيار GS1:

  • (01) = GTIN (معرف المنتج العالمي)
  • 03212345678906 = رمز المنتج الفعلي
  • (21) = معرف الرقم التسلسلي
  • A1B2C3D4E5F6G7H8 = تسلسل فريد

يمكنك استبدالها بأي نص لرموز QR، Code128، DataMatrix، إلخ. يتم دعم أكثر من 60 نوع باركود—انظر وثائق GroupDocs للقائمة الكاملة.

كيف تقوم بوضع وتخصيص الباركود؟

يتم التحكم في الموقع والتنسيق عبر نفس كائن BarcodeSignOptions. استخدم setTop، setLeft، setWidth، و setHeight لتحديد الإحداثيات والأبعاد بدقة. ضبط setAllPages(true) يضيف الباركود إلى كل صفحة تلقائيًا، بينما setPageNumber(1) يستهدف صفحة محددة. يمكنك أيضًا تدوير الباركود، إضافة لون خلفية، أو تعديل الهوامش لضمان عدم تداخل الباركود مع المحتوى الموجود.

// Set position and apply to all pages
options.setTop(200); // Set vertical position
options.setAllPages(true);

لتحكم أكثر دقة في التخطيط، يمكنك أيضًا تثبيت الباركود إلى صفحة معينة، تدويره، أو إضافة لون خلفية:

options.setLeft(100);        // 100 pixels from left edge
options.setTop(200);         // 200 pixels from top
options.setWidth(300);       // Barcode width in pixels
options.setHeight(100);      // Barcode height in pixels
options.setPageNumber(1);    // Only sign page 1 (removes setAllPages)

التخصيص البصري (ألوان المقدمة/الخلفية، الهوامش، تسميات النص) متاح عبر خصائص إضافية:

options.setMargin(new Padding(10));           // Add padding around barcode
options.setBackground(new Background());       // Set background color
options.setForeColor(Color.BLACK);            // Barcode color
options.setBackgroundColor(Color.WHITE);      // Background color

كيف تقوم بتوقيع المستند باستخدام باركود؟

طريقة sign على كائن Signature تطبق الخيارات المكوّنة وتكتب المستند الموقّع إلى القرص. تُعيد كائن SignResult يخبرك بعدد التوقيعات التي تم تطبيقها وما إذا كانت هناك تحذيرات. هذه الطريقة تتعامل مع جميع عمليات معالجة PDF منخفضة المستوى، لذا لا تحتاج إلى العمل مع مكتبات PDF مباشرة.

try {
    SignResult signResult = signature.sign(outputPath, options);
    System.out.println("Document signed successfully!");
    System.out.println("Signed document saved to: " + outputPath);
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

كتلة try‑finally المحيطة تضمن تحرير كائن Signature حتى في حالة حدوث استثناء، مما يمنع تسرب مقبض الملف.

يمكنك فحص SignResult لتأكيد النجاح:

if (signResult.getSucceeded().size() > 0) {
    System.out.println("Successfully added " + signResult.getSucceeded().size() + " signature(s)");
}

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

بدمج كل شيء معًا، إليك طريقة واحدة تقوم بتحميل PDF، إضافة باركود GS1CompositeBar، وحفظ الملف الموقّع:

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

public class BarcodeSigningExample {
    
    public void signPdfWithBarcode(String inputPath, String outputPath) {
        Signature signature = null;
        
        try {
            // Initialize signature
            signature = new Signature(inputPath);
            
            // Configure barcode
            BarcodeSignOptions options = new BarcodeSignOptions(
                "(01)03212345678906/(21)A1B2C3D4E5F6G7H8"
            );
            options.setEncodeType(BarcodeTypes.GS1CompositeBar);
            options.setTop(200);
            options.setAllPages(true);
            
            // Sign and save
            SignResult result = signature.sign(outputPath, options);
            
            System.out.println("Signing completed: " + result.getSucceeded().size() + " signature(s) added");
            
        } catch (Exception e) {
            System.err.println("Error signing document: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (signature != null) {
                signature.dispose();
            }
        }
    }
}

هذه الطريقة جاهزة للإنتاج: تتحقق من صحة المدخلات، تدير الموارد، وتبلغ عن النتيجة.

كيف تضيف كل من التوقيعات الرقمية وتوقيعات الباركود؟

لتحقيق أقصى قدر من الأمان، أضف توقيعًا رقميًا تشفيرياً أولاً، ثم ضع الباركود فوقه. يضمن التوقيع الرقمي سلامة المستند، بينما يوفر الباركود تحققًا بصريًا سريعًا وبيانات قابلة للقراءة آليًا. استخدم الفئة DigitalSignOptions للخطوة الأولى ثم طبّق BarcodeSignOptions كما هو موضح أعلاه.

// First, add digital signature
DigitalSignOptions digitalOptions = new DigitalSignOptions("certificate.pfx");
digitalOptions.setPassword("cert_password");
signature.sign(outputPath, digitalOptions);

// Then, add barcode on top
BarcodeSignOptions barcodeOptions = new BarcodeSignOptions("DATA");
barcodeOptions.setEncodeType(BarcodeTypes.QR);
signature.sign(outputPath, barcodeOptions);

النتيجة هي PDF يحمل توقيعًا قانونيًا (رقمي) ويمكن قراءته فورًا بواسطة أي ماسح باركود.

العمل مع أنواع باركود مختلفة

تغيير تنسيقات الباركود سهل كاستبدال قيمة enum واحدة. المثال التالي يستبدل GS1CompositeBar برمز QR:

// Define barcode sign options with sample text
BarcodeSignOptions options = new BarcodeSignOptions("Sample Text");

// Assign specific barcode type
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

وهنا نفس التغيير لباركود خطي Code128:

options.setEncodeType(BarcodeTypes.QR);           // QR code
options.setEncodeType(BarcodeTypes.Code128);      // Code 128
options.setEncodeType(BarcodeTypes.DataMatrix);   // Data Matrix

تذكر أن كل نوع باركود له حدود سعة بيانات خاصة—رموز QR يمكنها حمل آلاف الأحرف، بينما Code39 يقتصر على الأحرف الأبجدية الرقمية.

حالات الاستخدام الواقعية

إدارة سلسلة التوريد

تضمين GS1CompositeBar على قوائم الشحن يتيح للموظفين في المستودعات مسح أرقام الطلبات، الوجهات، ورموز الدفعات دون فتح ملف PDF.

BarcodeSignOptions options = new BarcodeSignOptions(
    "(01)" + gtin + "/(21)" + serialNumber + "/(10)" + batchNumber
);
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

توثيق الرعاية الصحية

يمكن مسح رموز QR على نماذج الموافقة لتسجيل المستند تلقائيًا تحت سجل المريض الصحيح.

String patientData = "PATIENT_ID:" + patientId + "|DOC_TYPE:CONSENT|DATE:" + dateString;
BarcodeSignOptions options = new BarcodeSignOptions(patientData);
options.setEncodeType(BarcodeTypes.QR);

الخدمات المالية

معرفات المعاملات المشفرة في باركود تمكّن المدققين من التحقق من الامتثال بمسح بسيط.

String complianceData = "TXN:" + transactionId + "|AGENT:" + agentId + "|BRANCH:" + branchCode;
BarcodeSignOptions options = new BarcodeSignOptions(complianceData);
options.setEncodeType(BarcodeTypes.PDF417);

مراقبة جودة التصنيع

تقارير الفحص الموقّعة بباركود يحتوي على أرقام الدفعات ومعرفات المفتش تجعل تحليل السبب الجذري فوريًا.

String qcData = "BATCH:" + batchNumber + "|INSPECTOR:" + inspectorId + "|RESULT:" + passFailStatus;
BarcodeSignOptions options = new BarcodeSignOptions(qcData);
options.setEncodeType(BarcodeTypes.DataMatrix);

مشكلات التنفيذ الشائعة

المشكلة 1: استثناء “File is already in use”

الإجابة: يبقى الملف مقفلاً إذا لم يتم تحرير كائن Signature السابق. احرص دائمًا على تغليف كود التوقيع بكتلة try‑finally واستدعاء signature.dispose().

Signature signature = null;
try {
    signature = new Signature(filePath);
    // ... your code ...
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

المشكلة 2: الباركود لا يظهر في PDF

الإجابة: تحقق من أن قيم setTop/setLeft ضمن حدود الصفحة، زد من عرض/ارتفاع الباركود، وتأكد من تباين ألوان المقدمة/الخلفية مع خلفية الصفحة.

// Make sure dimensions are reasonable
options.setTop(100);      // Not 10000
options.setLeft(100);
options.setWidth(300);    // At least 200 pixels for readability
options.setHeight(100);

// Ensure contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

المشكلة 3: استثناء “Invalid Barcode Data”

الإجابة: تتطلب باركودات GS1 تنسيق أقواس صارم. استخدم معرفات التطبيقات الصحيحة (مثل (01)، (21)) وتجنب الأحرف غير المدعومة.

// Correct:
"(01)03212345678906/(21)ABC123"

// Incorrect:
"03212345678906ABC123"

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

الإجابة: زد حجم heap للـ JVM (-Xmx4G) وفكّر في توقيع الصفحات بشكل فردي بدلاً من استخدام setAllPages(true) للوثائق الضخمة جدًا.

java -Xmx2G -jar your-application.jar

المشكلة 5: فشل مسح الباركود

الإجابة: تأكد من أن الباركود لا يقل عن 200 × 100 px، يستخدم ألوانًا ذات تباين عالي، ولا يتشوه بسبب ضغط PDF.

// Increase size
options.setWidth(400);
options.setHeight(150);

// Maximize contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

// Add quiet zone (blank space around barcode)
options.setMargin(new Padding(10));

الأمان والتحقق

هل توقيعات الباركود آمنة؟

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

التحقق من بيانات الباركود

بعد المسح، تحقق من أن التوقيع الرقمي للمستند لا يزال صالحًا وأن حمولة الباركود تطابق الأنماط المتوقعة. استخدم API search() من GroupDocs مع BarcodeSearchOptions لاستخراج محتوى الباركود والتحقق منه تلقائيًا.

public boolean validateScannedBarcode(String scannedData, String documentPath) {
    // Verify digital signature first
    if (!verifyDigitalSignature(documentPath)) {
        return false;
    }
    
    // Validate barcode format
    if (!scannedData.matches("(01)\\d{14}/(21)[A-Z0-9]+")) {
        return false;
    }
    
    // Check against database
    String productId = extractProductId(scannedData);
    return database.productExists(productId);
}

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

إدارة الموارد

احرص دائمًا على تحرير كائنات Signature بعد كل عملية لتجنب تسرب الذاكرة:

signature.dispose();

عند معالجة العديد من الملفات، أنشئ وحرّر كائن Signature جديد لكل مستند:

for (String filePath : documentPaths) {
    Signature signature = null;
    try {
        signature = new Signature(filePath);
        // ... signing logic ...
    } finally {
        if (signature != null) {
            signature.dispose();
        }
    }
}

معالجة الدفعات

للدفعات الصغيرة (< 100 ملف)، المعالجة المتسلسلة بسيطة:

for (String path : paths) {
    signDocument(path);
}

للأحمال الكبيرة، يمكن أن تسرّع المعالجة المتوازية الأمور—لكن راقب ضغط I/O وحدد عدد الخيوط بين 4‑8:

paths.parallelStream().forEach(path -> signDocument(path));

تحسين الذاكرة لملفات PDF الكبيرة

زد حجم heap، عالج الصفحات بشكل فردي، وامسح المراجع بعد كل خطوة. هذا يمنع OutOfMemoryError على المستندات التي تزيد عن 50 MB.

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

إذا كنت تعيد استخدام نفس تكوين الباركود عبر ملفات متعددة، احفظ كائن BarcodeSignOptions في ذاكرة مؤقتة:

// Create once, reuse many times
private static BarcodeSignOptions createStandardBarcodeOptions(String data) {
    BarcodeSignOptions options = new BarcodeSignOptions(data);
    options.setEncodeType(BarcodeTypes.GS1CompositeBar);
    options.setTop(200);
    options.setAllPages(true);
    return options;
}

الميزات المتقدمة

توقيعات متعددة على مستند واحد

أضف عدة باركودات (أو امزجها مع توقيعات رقمية) عن طريق استدعاء sign عدة مرات مع كائنات خيارات مختلفة:

// Add QR code in top-left
BarcodeSignOptions qrOptions = new BarcodeSignOptions("https://example.com");
qrOptions.setEncodeType(BarcodeTypes.QR);
qrOptions.setTop(50);
qrOptions.setLeft(50);
signature.sign(outputPath, qrOptions);

// Add GS1 barcode in bottom-right
BarcodeSignOptions gs1Options = new BarcodeSignOptions("(01)03212345678906");
gs1Options.setEncodeType(BarcodeTypes.GS1CompositeBar);
gs1Options.setTop(700);
gs1Options.setLeft(400);
signature.sign(outputPath, gs1Options);

محتوى باركود ديناميكي

أنشئ بيانات الباركود من بيانات تعريف المستند، الطوابع الزمنية، أو استعلامات قاعدة البيانات:

// Extract data from PDF or database
String orderId = extractOrderIdFromPdf(filePath);
String timestamp = LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME);
String barcodeData = String.format("ORDER:%s|TIME:%s", orderId, timestamp);

BarcodeSignOptions options = new BarcodeSignOptions(barcodeData);

التكامل مع Spring Boot

اعرض نقطة نهاية REST تستقبل PDF، تضيف باركود، وتعيد الملف الموقّع:

@Service
public class DocumentSigningService {
    public void signWithBarcode(MultipartFile file, String barcodeData) {
        // ... implementation ...
    }
}

مثال على REST API

متحكم بسيط يوجه الطلب إلى خدمة التوقيع:

@PostMapping("/sign-document")
public ResponseEntity<byte[]> signDocument(
    @RequestParam("file") MultipartFile file,
    @RequestParam("barcode") String barcodeData
) {
    // Sign document and return as byte array
}

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

س: ما هو باركود GS1CompositeBar؟
ج: يجمع GS1CompositeBar بين مكونات خطية وثنائية الأبعاد لتخزين معرفات المنتجات، الأرقام التسلسلية، وبيانات أخرى في رمز واحد قابل للمسح، ويُستخدم على نطاق واسع في التجزئة واللوجستيات.

س: هل يمكنني استخدام أنواع باركود أخرى غير GS1CompositeBar؟
ج: نعم—يدعم GroupDocs.Signature أكثر من 60 نوعًا، بما في ذلك QR، Code128، DataMatrix، PDF417، وAztec. غيّر قيمة setEncodeType() لتغيير الصيغة.

س: هل أحتاج إلى ترخيص للاستخدام في الإنتاج؟
ج: يلزم وجود ترخيص GroupDocs صالح للنشر في بيئات الإنتاج. تتوفر نسخة تجريبية مجانية للتطوير والاختبار.

س: هل يقرأ ماسحات الباركود الباركودات من ملفات PDF الموقّعة؟
ج: بالتأكيد، بشرط أن يكون الباركود على الأقل 200 × 100 px ويملك تباينًا كافيًا. تطبيقات مسح الهواتف الذكية تعمل على الشاشة؛ أما الماسحات المادية فتعمل على النسخ المطبوعة.

س: كيف أتعامل مع الأخطاء أثناء التوقيع؟
ج: غلف الكود بكتل try‑catch، سجّل تفاصيل الاستثناء بالكامل، واحرص دائمًا على استدعاء signature.dispose() داخل كتلة finally لتحرير الموارد.

س: هل يمكنني توقيع صيغ مستندات أخرى؟
ج: نعم—يدعم GroupDocs.Signature أيضًا DOCX، XLSX، PPTX، الصور، والعديد غيرها. ما عليك سوى تغيير امتداد ملف الإدخال؛ يبقى الـ API كما هو.

س: هل هناك حدود لحجم الملفات؟
ج: لا يوجد حد صريح، لكن المستندات التي تزيد عن 50 MB قد تتطلب زيادة حجم heap للـ JVM ومعالجة صفحة بصفحة للحفاظ على كفاءة الذاكرة.

س: كيف أوقع ملفات PDF المخزنة في التخزين السحابي؟
ج: حمّل الملف إلى مسار محلي مؤقت، طبّق التوقيع، ثم ارفع الملف مرة أخرى إلى دلو السحابة الخاص بك. احذف الملفات المؤقتة بعد الانتهاء.

الخلاصة

أنت الآن تمتلك دليلًا كاملاً وجاهزًا للإنتاج لإنشاء create barcode signature java لمستندات PDF. من خلال دمج التوقيعات الرقمية المشفرة مع باركودات قابلة للقراءة آليًا، تحقق كلًا من القوة القانونية والكفاءة التشغيلية عبر سلاسل التوريد، الرعاية الصحية، المالية، والتصنيع. جرّب أنواع باركود مختلفة، دمج الكود في خدماتك الحالية، واستكشف معالجة الدفعات للنشر على نطاق واسع.

Last Updated: 2026-05-21
Tested With: GroupDocs.Signature 23.10 for Java
Author: GroupDocs

String filePath = "YOUR_DOCUMENT_DIRECTORY" + "/sample.pdf";
String fileName = new java.io.File(filePath).getName();
String outputPath = "YOUR_OUTPUT_DIRECTORY" + "/SignedWithBarcodeGS1CompositeBar/" + fileName;

String documentDir = System.getenv("DOCUMENT_DIR");
String outputDir = System.getenv("OUTPUT_DIR");

Signature signature = new Signature(filePath);

دروس ذات صلة