คุณสมบัติหลักของ 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 ที่อยู่ในสโคปการทดสอบ.

การประกาศ library, โพสต์ facades, และโพสต์ page-editing ได้ครอบคลุมการสร้างเอกสาร, ฟิลด์ฟอร์ม, คลาสฟาซาดสำหรับการสกัดข้อมูล, การเข้ารหัส, และการประทับ, รวมถึงการดำเนินการกับหน้าโดยใช้ PdfFileEditor แล้ว โพสต์นี้ครอบคลุมหัวข้ออื่นอีกห้าหัวข้อของ API เดียวกันที่โพสต์เหล่านั้นไม่ได้แสดง: text-markup annotations, free-text callouts, document-level actions, a size guard on stream decoding, and diagnostic logging.

แต่ละพื้นที่เป็น API เล็ก ๆ ที่แยกออกจากกัน ส่วนต่อไปนี้แสดงการเรียกใช้, ค่าเริ่มต้น, และกรณีขอบที่การทดสอบของไลบรารีกำหนดไว้.

คุณสมบัติสำคัญ

การทำเครื่องหมายข้อความ (Text Markup Annotations)

HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation และ SquigglyAnnotation แต่ละตัวรับ Page และ Rectangle. ตัวสร้าง (constructor) จะสกัดจุดสี่เหลี่ยม (quad points) ของ annotation จากสี่เหลี่ยม, ดังนั้น getQuadPoints() จะคืนค่าแปดค่าโดยไม่ต้องคำนวณด้วยตนเอง. สำหรับสี่เหลี่ยม (100, 200, 300, 250) ผลลัพธ์คือ [100, 250, 300, 250, 100, 200, 300, 200]: ซ้ายบน, ขวาบน, ซ้ายล่าง, แล้วขวาล่าง. setQuadPoints() จะแทนค่าที่สกัดด้วยอาเรย์แปดค่าของคุณ, และ annotation ที่สร้างใหม่จากพจนานุกรมที่มีอยู่จะเก็บจุดสี่เหลี่ยมที่บันทึกไว้แล้ว. getSubtype() คืนชื่อ subtype ของ PDF: Highlight, Underline, StrikeOut, หรือ Squiggly.

การสร้าง annotation ไม่ได้แนบมันกับหน้า. เพิ่มด้วย 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, ซึ่งบรรจุชื่อฟอนต์, ขนาดฟอนต์, และสีข้อความ. สามคุณสมบัติกำหนดรูปแบบของ callout:

• setIntent() รับ FreeTextIntent: FreeText, FreeTextCallout, หรือ FreeTextTypeWriter. annotation ใหม่รายงาน Undefined, และการส่ง null จะคืนกลับสู่สถานะนั้น.
• setCallout() รับเส้น callout เป็นอาเรย์ของจุด {x, y} สองหรือสามจุด. อาเรย์ที่มีความยาวอื่นจะถูกละเว้นและ callout ที่มีอยู่จะคงอยู่; null จะลบ callout.
• setEndingStyle() รับค่าประเภท LineEnding เช่น OpenArrow หรือ Diamond. annotation ใหม่รายงาน 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");
}

พจนานุกรม annotation ที่บันทึกไว้เก็บค่าต่าง ๆ เหล่านี้เป็น /IT, /CL, และ /LE.

การกระทำระดับเอกสาร

Document.getActions() คืนค่ามุมมอง DocumentActions ของแคตตาล็อกเอกสาร. setOpenAction() เก็บการกระทำในรายการ /OpenAction ของแคตตาล็อก. ตัวกระตุ้นเพิ่มเติมอีกห้าตัวคือ setBeforeClosing(), setBeforeSaving(), setAfterSaving(), setBeforePrinting() และ setAfterPrinting(), ถูกเก็บแยกจากกันในพจนานุกรม additional-actions ของแคตตาล็อก /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, แทนที่จะถอดรหัสจนหน่วยความจำหมด.

ขีดจำกัดเริ่มต้นคือ 256MB ต่อสตรีมที่ถอดรหัส (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 ภายใต้ logger 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 เปลี่ยนเฉพาะ subtree ของ logger org.aspose.pdf. มันไม่เปลี่ยนระดับของ root logger, และ library logger ไม่ส่งบันทึกไปยัง handler ของ root logger. หากการบันทึกถูกเปิดใช้งานและไม่มี handler ใดแนบกับ library logger, จะติดตั้ง console handler.

// 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 ไปยังการสร้างของคุณ:

<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 หรือใหม่กว่า.

เริ่มต้น

• เริ่มต้นใช้งาน
• คู่มือผู้พัฒนา
• บทความ KB
• API Reference

แหล่งข้อมูลที่เกี่ยวข้อง

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