תכונות מרכזיות של 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. הבונה (constructor) נגזר את נקודות הקוונט של ההערה מהמלבן, ולכן 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 של הקטלוג.

כל getter מחזיר null עד שהמתג שלו מוגדר. העברת null ל-setter מסירה את הרשומה הזאת, והסרת המתג האחרון מסירה גם את מילון /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 מבצעים מעבר נתונים (round-trip) דרך 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