الميزات الأساسية لـ Aspose.PDF FOSS for Java

مقدمة

Aspose.PDF FOSS لـ Java هي مكتبة Java مرخصة تحت رخصة MIT لإنشاء وتعديل مستندات PDF. تم تنظيم فصولها تحت حزمة org.aspose.pdf وحزمها الفرعية (org.aspose.pdf.annotations، org.aspose.pdf.forms، org.aspose.pdf.facades، وغيرها)، وDocument هي نقطة الدخول لمعظم سير العمل. لا تحتوي المكتبة على أي تبعيات تشغيلية من طرف ثالث؛ التبعية الوحيدة في بناء Maven هي JUnit، في نطاق الاختبار.

إعلان المكتبة، منشور الواجهات، ومنشور تحرير الصفحات تغطي بالفعل إنشاء المستندات، حقول النماذج، فئات الواجهة للاستخراج، التشفير، والختم، وعمليات الصفحات باستخدام PdfFileEditor. تغطي هذه المشاركة خمسة مجالات أخرى من نفس API التي لا توضحها تلك المشاركات: تعليقات توضيحية للنص، ملاحظات نصية حرة، إجراءات على مستوى المستند، حماية الحجم عند فك ترميز الدفق، وتسجيل تشخيصي.

كل مجال هو API صغير ومُستقل. تُظهر الأقسام أدناه الاستدعاءات، الإعدادات الافتراضية، وحالات الحافة التي تحددها اختبارات المكتبة نفسها.

الميزات الرئيسية

تعليقات توضيحية للنص

HighlightAnnotation، UnderlineAnnotation، StrikeOutAnnotation، وSquigglyAnnotation كل منها يأخذ Page وRectangle. المُنشئ يستخلص نقاط المربعات للتعليق من المستطيل، لذا getQuadPoints() يرجع ثمانية قيم دون أي حساب يدوي. بالنسبة للمستطيل (100, 200, 300, 250) النتيجة هي [100, 250, 300, 250, 100, 200, 300, 200]: أعلى اليسار، أعلى اليمين، أسفل اليسار، ثم أسفل اليمين. setQuadPoints() يستبدل القيم المستخلصة بمصفوفتك ذات الثماني قيم، وتعليق يُعاد بناؤه من قاموس موجود يحتفظ بنقاط المربعات المخزنة هناك. getSubtype() يرجع اسم النوع الفرعي للـ PDF: Highlight، Underline، StrikeOut، أو Squiggly.

إنشاء تعليق توضيحي لا يرفقه بالصفحة. أضفه باستخدام page.getAnnotations().add(...).

try (Document doc = new Document()) {
    Page page = doc.getPages().add();

    HighlightAnnotation highlight = new HighlightAnnotation(page, new Rectangle(100, 200, 300, 250));
    double[] quadPoints = highlight.getQuadPoints();

    UnderlineAnnotation underline = new UnderlineAnnotation(page, new Rectangle(50, 100, 200, 120));
    StrikeOutAnnotation strikeOut = new StrikeOutAnnotation(page, new Rectangle(50, 140, 200, 160));
    SquigglyAnnotation squiggly = new SquigglyAnnotation(page, new Rectangle(50, 180, 200, 200));

    page.getAnnotations().add(highlight);
    page.getAnnotations().add(underline);
    page.getAnnotations().add(strikeOut);
    page.getAnnotations().add(squiggly);
    doc.save("markup.pdf");
}

ملاحظات نصية حرة

FreeTextAnnotation يضع النص مباشرةً على الصفحة. مُنشئه ذو الثلاثة معطيات يأخذ DefaultAppearance، الذي يحتوي على اسم الخط، حجم الخط، ولون النص. ثلاث خصائص تشكل الملاحظة:

• setIntent() يأخذ FreeTextIntent: FreeText أو FreeTextCallout أو FreeTextTypeWriter. يُبلغ التعليق التوضيحي الجديد عن Undefined، وتمرير null يعيده إلى تلك الحالة.
• setCallout() يأخذ خط الملاحظة كمصفوفة من نقطتين أو ثلاث نقاط {x, y}. أي مصفوفة بطول مختلف تُهمل وتبقى الملاحظة الحالية في مكانها؛ null يزيل الملاحظة.
• setEndingStyle() يأخذ قيمة LineEnding مثل OpenArrow أو Diamond. يُبلغ التعليق التوضيحي الجديد عن LineEnding.None.

try (Document doc = new Document()) {
    Page page = doc.getPages().add();
    DefaultAppearance da = new DefaultAppearance("Helv", 10, Color.BLACK);
    FreeTextAnnotation note = new FreeTextAnnotation(page, new Rectangle(50, 50, 200, 100), da);

    note.setContents("Check this value");
    note.setIntent(FreeTextIntent.FreeTextCallout);
    note.setCallout(new double[][] {{10, 10}, {50, 50}, {100, 100}});
    note.setEndingStyle(LineEnding.OpenArrow);

    page.getAnnotations().add(note);
    doc.save("callout.pdf");
}

يخزن القاموس المحفوظ للتعليقات التوضيحية هذه القيم كـ /IT، /CL، و/LE.

إجراءات على مستوى المستند

Document.getActions() يعيد عرضًا DocumentActions لكاتالوج المستندات. setOpenAction() يخزن إجراءً في إدخال /OpenAction في الكاتالوج. يتم تخزين خمسة مشغلات أخرى، setBeforeClosing()، setBeforeSaving()، setAfterSaving()، setBeforePrinting() وsetAfterPrinting()، بشكل مستقل في القاموس /AA للإجراءات الإضافية في الكاتالوج.

كل دالة جلب تُعيد null حتى يتم ضبط المشغل الخاص بها. تمرير null إلى دالة ضبط يزيل ذلك الإدخال، وإزالة آخر مشغل يزيل أيضًا القاموس /AA. الإجراءات هي حالات PdfAction; GoToURIAction هو اسم مستعار لـ UriAction، وgetType() الخاص به يُعيد URI. كائن DocumentActions هو عرض حي، لذا نداء لاحق لـ getActions() يرى التغييرات التي أُجريت عبر نداء سابق، وتُقرأ المشغلات مرة أخرى عند فتح الملف المحفوظ مرة أخرى.

try (Document doc = new Document()) {
    doc.getPages().add();
    DocumentActions actions = doc.getActions();

    actions.setOpenAction(new GoToURIAction("https://example.com"));
    actions.setBeforeSaving(new GoToURIAction("https://example.com/saving"));

    PdfAction open = doc.getActions().getOpenAction();
    if (open instanceof UriAction) {
        System.out.println(((UriAction) open).getUri());
    }

    actions.setBeforeSaving(null);   // removes /WS; /AA is removed once it is empty
    doc.save("actions.pdf");
}

حدود فك الترميز لمرشحات التدفق

يتم تخزين تدفقات PDF بشكل مشفر، ويمكن لتدفق فاسد أو خبيث أن يتوسع إلى أكثر بكثير من حجمه المخزن. DecodeLimits هو حارس مشترك بين مرشحات FlateDecode وLZWDecode و RunLengthDecode. عندما يتجاوز ناتج فك الترميز لتدفق ما الحد الأقصى، يقوم المرشح بإلقاء DecodeSizeLimitException، وهو فئة فرعية من IOException، بدلاً من الاستمرار في فك الترميز حتى استنفاد الذاكرة المؤقتة.

الحد الافتراضي هو 256 ميغابايت لكل تدفق مُفكّك (DecodeLimits.DEFAULT_MAX_DECODED_BYTES). لتغييره، اضبط خاصية النظام التي يُسمى اسمها DecodeLimits.PROPERTY، والتي هي aspose.pdf.maxDecodedStreamBytes، إلى حجم بالبايت؛ قيمة 0 أو أقل تُعطّل الحارس. تُقرأ الخاصية عند كل عملية فك، لذا يمكن تعديلها أثناء التشغيل.

static byte[] decodeFlate(byte[] encoded) {
    // Lower the cap to 16 MB (16777216 bytes) for this process
    System.setProperty(DecodeLimits.PROPERTY, "16777216");
    try {
        return new FlateFilter().decode(encoded, null);
    } catch (IOException e) {
        // "FlateDecode: decoded output exceeds 16777216 bytes - likely a corrupt stream
        //  or decompression bomb (override with -Daspose.pdf.maxDecodedStreamBytes)"
        return null;
    }
}

تُفكّ التدفقات التي هي تحت الحد كالمعتاد. FlateFilter وRunLengthFilter كلاهما يمرران البيانات ذهابًا وإيابًا عبر encode() وdecode() عندما يبقى الناتج تحت الحد.

تسجيل التشخيص

تقوم المكتبة بتسجيل السجلات عبر java.util.logging تحت مسجل org.aspose.pdf وتكون صامتة افتراضيًا: المستوى هو OFF. AsposePdfLogging يُفعّل التسجيل.

• setLevel(Level) يضبط المستوى من الكود؛ null يعيد المكتبة إلى OFF. getLevel() يقرأها مرة أخرى.
• خاصية النظام aspose.pdf.log (متاحة أيضًا باسم AsposePdfLogging.LOG_PROPERTY) تضبطها من سطر الأوامر. configureFromSystemProperty() يطبق الخاصية ويعمل أيضًا عند تحميل الفئة. القيم on وwarning تختار WARNING، verbose تختار FINE، debug تختار ALL، أي اسم java.util.logging.Level مثل SEVERE مقبول، والقيمة غير المعروفة تعود إلى OFF.

WARNING يسمح بمرور تحذيرات المحرك؛ FINE، إعداد verbose، يسمح أيضًا بمرور تفاصيل استعادة المحلل. AsposePdfLogging يغيّر فقط شجرة السجل الفرعية org.aspose.pdf. لا يغيّر مستوى سجل الجذر، ولا يقوم سجل المكتبة بتمرير السجلات إلى معالجات سجل الجذر. إذا كان التسجيل مفعلاً ولا يوجد معالج مرفق بسجل المكتبة، يتم تثبيت معالج وحدة تحكم.

// Equivalent to starting the JVM with -Daspose.pdf.log=warning
AsposePdfLogging.setLevel(Level.WARNING);

System.setProperty(AsposePdfLogging.LOG_PROPERTY, "verbose");
AsposePdfLogging.configureFromSystemProperty();
System.out.println(AsposePdfLogging.getLevel());   // FINE

البدء السريع

أضف الاعتماد إلى عملية البناء الخاصة بك:

<dependency>
  <groupId>org.aspose</groupId>
  <artifactId>aspose-pdf-foss</artifactId>
  <version>26.8.0</version>
</dependency>

المثال التالي ينشئ صفحة، يضيف تظليلًا وإشارة نصية حرة، ويحفظ المستند:

import org.aspose.pdf.*;
import org.aspose.pdf.annotations.*;

try (Document doc = new Document()) {
    Page page = doc.getPages().add();

    page.getAnnotations().add(new HighlightAnnotation(page, new Rectangle(100, 200, 300, 250)));

    FreeTextAnnotation note = new FreeTextAnnotation(page, new Rectangle(50, 50, 200, 100),
            new DefaultAppearance("Helv", 10, Color.BLACK));
    note.setContents("Check this value");
    note.setIntent(FreeTextIntent.FreeTextCallout);
    note.setCallout(new double[][] {{10, 10}, {50, 50}, {100, 100}});
    page.getAnnotations().add(note);

    doc.save("core-features.pdf");
}

الصيغ المدعومة

دعم الصيغ كما تم تأكيده عبر خيارات التحميل والحفظ في المكتبة وأجهزة العرض:

المصدر المفتوح والترخيص

Aspose.PDF FOSS لـ Java تم إصداره تحت رخصة MIT، التي تسمح بالاستخدام التجاري، والتعديل، وإعادة التوزيع. الشيفرة المصدرية وتعقب القضايا متوفران على github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java. تستهدف المكتبة Java 11 أو أحدث.

البدء

• البدء
• دليل المطور
• مقالات قاعدة المعرفة
• API Reference

الموارد ذات الصلة

• Aspose.PDF — Enterprise Blog
• Aspose.PDF for Java — Enterprise Product