إضافة توقيع الباركود إلى ملفات PDF باستخدام GroupDocs.Signature Java

إجابات سريعة

• ما هو السطر الأول من الشيفرة لبدء التوقيع؟ Signature signature = new Signature("sample.pdf");
• ما هو العنصر (artifact) الخاص بـ Maven الذي أحتاجه؟ com.groupdocs:groupdocs-signature:23.10 (استبدله بأحدث نسخة)
• هل يمكنني توقيع ملفات PDF المحمية بكلمة مرور؟ نعم—مرّر كلمة المرور عند إنشاء كائن Signature.
• كم عدد صيغ الباركود المدعومة؟ أكثر من 30 صيغة، بما في ذلك Code128، QR، DataMatrix، وAztec.
• ما هو حجم الذاكرة (heap) الموصى به لملفات PDF بحجم 100 ميغابايت؟ على الأقل -Xmx2g (2 جيجابايت) لتجنب OutOfMemoryError.

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

الـ barcode signature هو باركود قابل للقراءة آليًا يتم تضمينه في ملف PDF ويعمل كعلامة تُظهر أي تعديل غير مصرح به ويمكنه حمل بيانات مخصصة مثل المعرفات، الطوابع الزمنية، أو عناوين URL. يجمع بين التحقق البصري والمسح الآلي، مما يجعله مثاليًا للجرد، والامتثال، وأتمتة سير العمل عالي الحجم.

لماذا نضيف توقيع الباركود باستخدام GroupDocs.Signature Java؟

يدعم GroupDocs.Signature أكثر من 50 صيغة إدخال وإخراج، يعالج ملفات PDF ذات مئات الصفحات دون تحميل الملف بالكامل إلى الذاكرة، ويوفر واجهة برمجة تطبيقات Java سلسة تتيح لك ضبط كل جانب بصري للباركود بدقة. في اختبارات الأداء، يستغرق توقيع ملف PDF مكوّن من 150 صفحة بباركود Code128 أقل من 1.2 ثانية على مثيل سحابي قياسي بموارد 2 vCPU.

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

قبل أن نبدأ، تأكد من أن لديك ما يلي:

• مجموعة تطوير جافا (JDK) 8 أو أحدث (يوصى بـ JDK 11 أو 17 للدعم طويل الأمد)
• بيئة تطوير متكاملة (IDE) (IntelliJ IDEA، Eclipse، أو VS Code مع امتدادات Java)
• أداة بناء (Maven 3.6+ أو Gradle 7.0+)
• مكتبة GroupDocs.Signature Java (سنوضح إعداد Maven وGradle أدناه)
• إلمام أساسي بمفاهيم OOP في جافا وهياكل مشاريع Maven/Gradle

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

يتكامل GroupDocs.Signature بسلاسة مع Maven أو Gradle. اختر أداة البناء التي تستخدمها بالفعل:

إعداد Maven

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

إعداد Gradle

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

إذا كنت تفضّل التعامل اليدوي مع ملفات JAR، قم بتحميل أحدث إصدار من GroupDocs.Signature for Java releases وأضفه إلى مسار الفئة (classpath) الخاص بك.

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

تقدم GroupDocs ثلاثة نماذج ترخيص:

• تجربة مجانية – وصول كامل للميزات لمدة 30 يومًا (يتم إضافة علامة مائية إلى ملفات PDF الموقعة)
• ترخيص مؤقت – تجربة ممتدة بدون حدود للميزات (مثالي لخطوط أنابيب التطوير)
• ترخيص كامل – جاهز للإنتاج، يتضمن دعمًا أولوية ولا علامات مائية

احصل على الترخيص المناسب من GroupDocs Licensing. حتى أثناء التجربة يمكنك تشغيل الشيفرة محليًا؛ فقط تذكّر استبدال مفتاح التجربة بواحد دائم قبل النشر.

كيف أضيف توقيع باركود إلى ملف PDF باستخدام GroupDocs.Signature Java؟

فئة Signature هي نقطة الدخول الرئيسية للعمل مع المستندات في GroupDocs.Signature.
فئة BarcodeSignOptions تحدد بيانات الباركود، نوعه، ومظهره البصري.

حمّل ملف PDF المصدر باستخدام new Signature("source.pdf")، واضبط كائن BarcodeSignOptions بالبيانات والنمط البصري المطلوب، ثم استدعِ signature.sign("output.pdf", options). هذا النمط المكوّن من ثلاث خطوات يتعامل مع إدخال/إخراج الملفات، توليد الباركود، وكتابة PDF في استدعاء واحد آمن للخطوط المتعددة، ويعمل مع ملفات PDF تتراوح من بضعة كيلوبايت إلى عدة مئات من الميجابايت.

الخطوة 1: تهيئة كائن Signature

فئة Signature هي نقطة الدخول في GroupDocs.Signature لجميع عمليات التوقيع. تمثل مستند PDF واحد في الذاكرة وتوفر تحميلًا كسولًا للحفاظ على استهلاك الذاكرة منخفضًا.

```java
import com.groupdocs.signature.Signature;

public class InitializeSignature {
    public static void main(String[] args) {
        Signature signature = new Signature("YOUR_DOCUMENT_DIRECTORY/sample.pdf");
        System.out.println("GroupDocs.Signature initialized successfully.");
    }
}

شرح:

• filePath يشير إلى ملف PDF المصدر الذي تريد توقيعه.
• outputFilePath هو المكان الذي سيُحفظ فيه ملف PDF الموقّع، مع الحفاظ على الملف الأصلي.
• كتلة try‑catch تضمن معالجة سلسة لأخطاء الإدخال/الإخراج، الملفات المفقودة، أو مشاكل الأذونات.

الخطوة 2: ضبط خيارات توقيع الباركود

BarcodeSignOptions يتيح لك تعريف كل سمة من سمات الباركود—النوع، البيانات، الموقع، الألوان، الحدود، وحتى ما إذا كان يجب إرجاع صورة الباركود الخام.

```java
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.exception.GroupDocsSignatureException;
import java.nio.file.Paths;
import java.io.File;

public class Feature1 {
    public static void run() throws Exception {
        String filePath = "YOUR_DOCUMENT_DIRECTORY/sample.pdf";
        String outputFilePath = new File("YOUR_OUTPUT_DIRECTORY", "SignedOutputSample.pdf").getPath();

        try {
            Signature signature = new Signature(filePath);
            System.out.println("Signature initialized and paths set.");
        } catch (Exception e) {
            throw new GroupDocsSignatureException(e.getMessage());
        }
    }
}

تفصيل الإعدادات الرئيسية:

• البيانات والنوع – "12345678" هي الحمولة؛ BarcodeTypes.Code128 يعمل مع سلاسل أبجدية رقمية وهو مدعوم على نطاق واسع من قبل الماسحات.
• الموضع – setLeft(100) و setTop(100) يبعدان الباركود 100 بكسل عن الزاوية العلوية اليسرى؛ VerticalAlignment.Top + HorizontalAlignment.Right يضبطان المحاذاة بالنسبة لتلك الإزاحات.
• الهوامش والمسافات الداخلية – كائن Padding يضيف مساحة 20 بكسل لتجنب القطع على حواف الصفحة.
• التنسيق – الحدود، الخط، وفرشاة الخلفية قابلة للتخصيص بالكامل؛ في بيئة الإنتاج قد تزيل التدرج لتحسين سرعة العرض.
• إرجاع المحتوى – تمكين setReturnContent(true) يمنحك الباركود كـ byte[]، وهو مفيد لتخزين الصورة في قاعدة بيانات أو عرضها في واجهة المستخدم.

تكوين بسيط جاهز للإنتاج

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

```java
import com.groupdocs.signature.domain.enums.*;
import com.groupdocs.signature.domain.Padding;
import com.groupdocs.signature.domain.Border;
import com.groupdocs.signature.domain.DashStyle;
import com.groupdocs.signature.domain.extensions.LinearGradientBrush;
import com.groupdocs.signature.domain.font.SignatureFont;
import java.awt.Color;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;

public class Feature2 {
    public static void configureBarcodeOptions() throws Exception {
        BarcodeSignOptions signOptions = new BarcodeSignOptions("12345678");
        signOptions.setEncodeType(BarcodeTypes.Code128);
        signOptions.setLeft(100);
        signOptions.setTop(100);
        signOptions.setVerticalAlignment(VerticalAlignment.Top);
        signOptions.setHorizontalAlignment(HorizontalAlignment.Right);

        Padding padding = new Padding();
        padding.setLeft(20);
        padding.setTop(20);
        signOptions.setMargin(padding);

        Border border = new Border();
        border.setColor(Color.GREEN);
        border.setDashStyle(DashStyle.DashLongDashDot);
        border.setWeight(2);
        border.setTransparency(0.5);
        border.setVisible(true);
        signOptions.setBorder(border);

        signOptions.setForeColor(Color.RED);
        SignatureFont font = new SignatureFont();
        font.setSize(12);
        font.setFamilyName("Comic Sans MS");
        signOptions.setFont(font);

        signOptions.setCodeTextAlignment(CodeTextAlignment.Above);

        Background background = new Background();
        background.setColor(Color.GREEN);
        background.setTransparency(0.5);
        background.setBrush(new LinearGradientBrush(Color.GREEN, Color.DARK_GRAY, 0));
        signOptions.setBackground(background);

        signOptions.setReturnContent(true);
        signOptions.setReturnContentType(FileType.PNG);
    }
}

الخطوة 3: توقيع المستند

طريقة sign تطبق الباركود المكوّن على ملف PDF وتكتب النتيجة إلى المسار المستهدف.

```java
signOptions.setEncodeType(BarcodeTypes.QR); // QR codes for more data
signOptions.setForeColor(Color.BLACK);
signOptions.setBackgroundColor(Color.WHITE);
// Remove border and fancy styling for professional appearance

ما يحدث في الخلفية:

• signature.sign(outputFilePath, signOptions) يكتب الباركود على ملف PDF مع ترك المصدر دون تعديل.
• SignResult يُبلغ عن عدد التوقيعات المضافة، الصفحات التي تم تعديلها، وأي تحذيرات تم إنشاؤها.
• للوظائف الدفعية، غلف هذا الاستدعاء داخل ExecutorService لتوزيع العمل على نوى المعالج.

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

المشكلة 1: FileNotFoundException عند التهيئة

العَرَض: التطبيق يرمي استثناء FileNotFoundException عند إنشاء كائن Signature.

الأسباب الجذرية:

• مسار ملف غير صحيح (نسبي مقابل مطلق)
• عدم وجود أذونات قراءة
• الملف مقفل بواسطة عملية أخرى (مثل فتحه في Acrobat)

الحل:

```java
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.exception.GroupDocsSignatureException;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.BaseSignature;

public class Feature3 {
    public static void signDocument(String filePath, BarcodeSignOptions signOptions) throws Exception {
        Signature signature = new Signature(filePath);
        String outputFilePath = filePath.replace(".pdf", "_Signed.pdf");

        try {
            com.groupdocs.signature.domain.signatures.SignResult signResult = signature.sign(outputFilePath, signOptions);
            System.out.println("Document signed successfully.");
        } catch (Exception e) {
            throw new GroupDocsSignatureException(e.getMessage());
        }
    }
}

تأكد من أن المسار يستخدم الشرطات المائلة للأمام (C:/Docs/sample.pdf) أو يهرب الشرطات المائلة الخلفية (C:\\Docs\\sample.pdf). تحقق من أذونات نظام التشغيل وأغلق أي برنامج قد يقفل الملف.

المشكلة 2: عدم ظهور الباركود في الناتج

العَرَض: يكتمل التوقيع دون أخطاء، لكن الباركود غير مرئي.

الأسباب الشائعة:

• الموضع يضع الباركود خارج منطقة الطباعة.
• تم ضبط الشفافية إلى 1.0 (شفاف بالكامل).
• تم ضبط حجم الخط إلى 0.

الحل:

• احتفظ بقيم setLeft/setTop داخل أبعاد الصفحة (0‑600 بكسل للـ A4 القياسي).
• استخدم قيمة شفافية بين 0.0 (معتم) و 0.9.
• اضبط حجم خط قابل للقراءة، مثل 12pt.

المشكلة 3: أخطاء نفاد الذاكرة مع المستندات الكبيرة

العَرَض: OutOfMemoryError عند معالجة ملفات PDF أكبر من ~50 ميغابايت.

الحلول:

• زيادة حجم الذاكرة في JVM: -Xmx2g أو أعلى حسب حجم المستند.
• معالجة ملف PDF صفحةً بصفحة باستخدام واجهة برمجة تطبيقات البث Signature.
• إغلاق كائن Signature صراحةً بعد كل عملية لتحرير الموارد الأصلية.

```java
import java.nio.file.Files;
import java.nio.file.Path;

Path filePath = Path.of("YOUR_DOCUMENT_DIRECTORY/sample.pdf");
if (!Files.exists(filePath)) {
    throw new IllegalArgumentException("PDF file not found: " + filePath);
}
if (!Files.isReadable(filePath)) {
    throw new SecurityException("Cannot read PDF file: " + filePath);
}
// Now safe to initialize
Signature signature = new Signature(filePath.toString());

المشكلة 4: خطأ بيانات باركود غير صالحة

العَرَض: تطرح الـ API استثناءً يشتكي من أحرف غير مدعومة.

السبب: معايير الباركود المختلفة تقبل مجموعات أحرف مختلفة. Code128 يسمح بالأحرف الأبجدية الرقمية؛ QR يمكنه التعامل مع Unicode؛ بعض الباركودات أحادية البعد تقبل الأرقام فقط.

الحل: اختر نوع الباركود الذي يتطابق مع مجموعة البيانات الخاصة بك، أو نظّف السلسلة قبل تعيينها إلى BarcodeSignOptions.

```java
String barcodeData = "ABC123"; // Your data
BarcodeTypes type = BarcodeTypes.Code128; // Alphanumeric support

// For numeric-only barcodes, validate first:
if (type == BarcodeTypes.EAN13 && !barcodeData.matches("\\d+")) {
    throw new IllegalArgumentException("EAN13 requires numeric data only");
}

أفضل الممارسات للإنتاج

1. التحقق من صحة ملفات PDF قبل التوقيع

دائمًا تأكد من أن الملف PDF مُشكل بشكل صحيح لتجنب أخطاء التحليل وقت التشغيل.

```java
try (Signature signature = new Signature(filePath)) {
    // If this succeeds, file is valid
    signature.getDocumentInfo();
} catch (Exception e) {
    // Handle invalid PDF
}

2. استخدم المعالجة غير المتزامنة لأعباء العمل عالية الحجم

انقل عملية التوقيع إلى مجموعة خيوط خلفية؛ هذا يمنع تجمّد واجهة المستخدم ويحسن معدل الإنتاجية.

```java
ExecutorService executor = Executors.newFixedThreadPool(4);
List<String> pdfFiles = Arrays.asList("doc1.pdf", "doc2.pdf", "doc3.pdf");

pdfFiles.forEach(file -> {
    executor.submit(() -> {
        try {
            signDocument(file, signOptions);
        } catch (Exception e) {
            // Log error
        }
    });
});
executor.shutdown();

3. تنفيذ تسجيل منظم

سجّل كل طلب توقيع مع مسار الإدخال، مسار الإخراج، بيانات الباركود، وأي استثناءات. هذا يسرّع بشكل كبير تحليل ما بعد الحادث.

```java
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(YourClass.class);

try {
    SignResult result = signature.sign(outputFilePath, signOptions);
    logger.info("Document signed successfully: {}", outputFilePath);
    logger.debug("Signatures added: {}", result.getSucceeded().size());
} catch (Exception e) {
    logger.error("Failed to sign document: {}", filePath, e);
}

4. تحسين إعدادات الباركود للسرعة

• عطل setReturnContent(true) ما لم تحتاج الصورة بشكل منفصل.
• فضل فرش الخلفية الصلبة على التدرجات.
• احذف الحدود لحالات الاستخدام البسيطة للتتبع.

5. التعامل بسلاسة مع انتهاء صلاحية الترخيص المؤقت

فئة License تقوم بتحميل والتحقق من ملف ترخيص GroupDocs لواجهة البرمجة.
تحقق من حالة الترخيص قبل كل عملية توقيع واستخدم وضع القراءة فقط أو نبه المسؤول.

```java
try {
    License license = new License();
    license.setLicense(licensePath);
} catch (Exception e) {
    logger.warn("License validation failed. Using trial mode.");
    // Continue with trial limitations
}

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

السيناريوهات المثالية

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

متى يُفضَّل استخدام أنواع توقيع أخرى

• العقود القانونية: استخدم توقيعات رقمية قائمة على PKI (مثل X.509) لضمان عدم الإنكار.
• ملفات PDF الموجهة للعملاء: رموز QR أكثر وضوحًا على الأجهزة المحمولة.
• المستندات فائقة الأمان: اجمع بين باركود وتوقيع رقمي مشفر لتوفير أمان متعدد الطبقات.

نصيحة احترافية: يمكنك دمج أنواع توقيع متعددة في نفس ملف PDF—أضف باركود للتتبع وشهادة رقمية للالتزام القانوني.

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

س: كيف أضيف توقيع باركود إلى ملف PDF في جافا بدون تبعيات خارجية؟
ج: مكتبة GroupDocs.Signature لـ Java مكتبة مستقلة؛ بعد إضافة عنصر Maven/Gradle ستحصل على توليد كامل للباركود وعرض PDF دون أي مكتبات طرف ثالث.

س: هل يمكنني ضبط خيارات توقيع الباركود في جافا لتوليد رموز QR؟
ج: بالطبع. غيّر تعداد BarcodeTypes إلى QRCode واضبط معلمات الحجم حسب الحاجة.

```java
signOptions.setEncodeType(BarcodeTypes.QR);

س: ما هو إعداد Maven الموصى به للاستخدام في الإنتاج؟
ج: حدد النسخة الدقيقة في pom.xml (مثلاً 23.10.0) لتجنب التحديثات غير المقصودة، وفعل إضافة Maven shade لإنتاج JAR واحد قابل للتنفيذ.

```xml
<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version> <!-- Don't use LATEST -->
</dependency>

س: هل تدعم المكتبة ملفات PDF محمية بكلمة مرور؟
ج: نعم. قدّم كلمة المرور عند إنشاء كائن Signature، ثم استمر في التوقيع كالمعتاد.

```java
LoadOptions loadOptions = new LoadOptions();
loadOptions.setPassword("your_pdf_password");
Signature signature = new Signature(filePath, loadOptions);

س: كم عدد الصفحات التي يمكنني توقيعها في عملية واحدة؟
ج: يمكن لـ GroupDocs.Signature معالجة جميع صفحات PDF مرة واحدة أو استهداف صفحات محددة عبر setPageNumber(). الأداء يتدرج خطيًا؛ ملف PDF مكوّن من 200 صفحة يُوقع في ~2 ثانية على جهاز سحابي نموذجي.

س: ما هي صيغ الباركود المتاحة بخلاف Code128؟
ج: أكثر من 30 صيغة، بما في ذلك QR، DataMatrix، Aztec، UPC‑A، EAN‑13، PDF417، وغيرها. راجع تعداد BarcodeTypes للقائمة الكاملة.

س: هل هناك حد لطول بيانات الباركود؟
ج: حدود الطول تعتمد على نوع الباركود؛ بالنسبة لـ Code128 الحد العملي هو 80 حرفًا، بينما رموز QR يمكنها تخزين ما يصل إلى 4 KB من البيانات.

س: هل يمكنني استرجاع صورة الباركود المولدة بعد التوقيع؟
ج: فعّل setReturnContent(true) و setReturnContentType(FileType.PNG)؛ سيتضمن SignResult مصفوفة byte[] يمكنك كتابتها إلى القرص أو قاعدة بيانات.

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

دروس ذات صلة

• كيفية إضافة توقيع رقمي في جافا - دليل GroupDocs الكامل
• إضافة رمز QR إلى PDF جافا - دليل GroupDocs الكامل
• إضافة توقيع نص إلى PDF في جافا - دليل GroupDocs الكامل