Wprowadzenie

Aspose.PDF FOSS dla Java jest biblioteką Java na licencji MIT służącą do tworzenia i edytowania dokumentów PDF. Jej klasy są zorganizowane w pakiecie org.aspose.pdf oraz jego podpakietach (org.aspose.pdf.annotations, org.aspose.pdf.forms, org.aspose.pdf.facades i innych), a Document jest punktem wejścia dla większości przepływów pracy. Biblioteka nie ma zależności uruchomieniowych od stron trzecich; jedyną zależnością w jej budowie Maven jest JUnit, w zakresie testów.

ogłoszenie biblioteki, post o fasadach oraz post o edycji stron już obejmują tworzenie dokumentów, pola formularzy, klasy fasadowe do ekstrakcji, szyfrowania i znakowania oraz operacje na stronach przy użyciu PdfFileEditor. Ten post omawia pięć dodatkowych obszarów tego samego API, których te posty nie pokazują: adnotacje tekstowe, wolnoformatowe notatki, akcje na poziomie dokumentu, ograniczenie rozmiaru przy dekodowaniu strumieni oraz logowanie diagnostyczne.

Każdy obszar jest małym, samodzielnym API. Poniższe sekcje przedstawiają wywołania, wartości domyślne oraz przypadki brzegowe, które własne testy biblioteki określają.

Kluczowe funkcje

Adnotacje znakowania tekstu

HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation i SquigglyAnnotation każdy przyjmuje Page oraz Rectangle. Konstruktor wyprowadza punkty kwadratu adnotacji z prostokąta, więc getQuadPoints() zwraca osiem wartości bez ręcznych obliczeń. Dla prostokąta (100, 200, 300, 250) wynik to [100, 250, 300, 250, 100, 200, 300, 200]: lewy-górny, prawy-górny, lewy-dolny, a następnie prawy-dolny. setQuadPoints() zastępuje wyprowadzone wartości własną tablicą ośmiu elementów, a adnotacja odtworzona z istniejącego słownika zachowuje już tam zapisane punkty kwadratu. getSubtype() zwraca nazwę podtypu PDF: Highlight, Underline, StrikeOut lub Squiggly.

Tworzenie adnotacji nie dołącza jej do strony. Dodaj ją za pomocą 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");
}

Wskazówki tekstowe

FreeTextAnnotation umieszcza tekst bezpośrednio na stronie. Jego konstruktor z trzema argumentami przyjmuje DefaultAppearance, który zawiera nazwę czcionki, rozmiar czcionki i kolor tekstu. Trzy właściwości kształtują wskazówkę:

  • setIntent() przyjmuje FreeTextIntent: FreeText, FreeTextCallout lub FreeTextTypeWriter. Nowa adnotacja zgłasza Undefined, a przekazanie null przywraca ją do tego stanu.
  • setCallout() przyjmuje linię wskazówki jako tablicę dwóch lub trzech punktów {x, y}. Tablica o innej długości jest ignorowana, a istniejąca wskazówka pozostaje na miejscu; null usuwa wskazówkę.
  • setEndingStyle() przyjmuje wartość LineEnding, taką jak OpenArrow lub Diamond. Nowa adnotacja zgłasza 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");
}

Zapisany słownik adnotacji przechowuje te wartości jako /IT, /CL i /LE.

Działania na poziomie dokumentu

Document.getActions() zwraca DocumentActions widok katalogu dokumentu. setOpenAction() przechowuje akcję w wpisie /OpenAction katalogu. Pięć dalszych wyzwalaczy, setBeforeClosing(), setBeforeSaving(), setAfterSaving(), setBeforePrinting() i setAfterPrinting(), jest przechowywanych niezależnie w słowniku dodatkowych akcji /AA katalogu.

Każdy getter zwraca null dopóki jego wyzwalacz nie zostanie ustawiony. Przekazanie null do settera usuwa ten wpis, a usunięcie ostatniego wyzwalacza usuwa także słownik /AA. Akcje są instancjami PdfAction; GoToURIAction jest aliasem UriAction, a jego getType() zwraca URI. Obiekt DocumentActions jest widokiem na żywo, więc późniejsze wywołanie getActions() widzi zmiany wprowadzone przez wcześniejsze, a wyzwalacze są odczytywane ponownie po otwarciu zapisanego pliku.

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");
}

Limity dekodowania dla filtrów strumieniowych

Strumienie PDF są przechowywane w formie zakodowanej, a uszkodzony lub złośliwy strumień może rozrosnąć się do znacznie większych rozmiarów niż jego zapisany rozmiar. DecodeLimits jest ochroną współdzieloną przez filtry FlateDecode, LZWDecode i RunLengthDecode. Gdy zdekodowany wynik strumienia przekracza limit, filtr zgłasza DecodeSizeLimitException, podklasę IOException, zamiast dekodować aż do wyczerpania stosu.

Domyślny limit wynosi 256MB na zdekodowany strumień (DecodeLimits.DEFAULT_MAX_DECODED_BYTES). Aby go zmienić, ustaw właściwość systemową określoną przez DecodeLimits.PROPERTY, która jest aspose.pdf.maxDecodedStreamBytes, na rozmiar w bajtach; wartość 0 lub mniejsza wyłącza ochronę. Właściwość jest odczytywana przy każdym dekodowaniu, więc może być zmieniana w czasie działania.

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;
    }
}

Strumienie mieszczące się w limicie są dekodowane jak zwykle. FlateFilter i RunLengthFilter oba przetwarzają dane w obie strony przez encode() i decode(), gdy wynik pozostaje poniżej limitu.

Diagnostyczne logowanie

Biblioteka loguje przez java.util.logging przy użyciu loggera org.aspose.pdf i jest domyślnie wyciszona: poziom to OFF. AsposePdfLogging włącza logowanie.

  • setLevel(Level) ustawia poziom z kodu; null przywraca bibliotekę do OFF. getLevel() odczytuje to z powrotem.
  • Właściwość systemowa aspose.pdf.log (dostępna także jako AsposePdfLogging.LOG_PROPERTY) ustawia ją z wiersza poleceń. configureFromSystemProperty() stosuje tę właściwość i jest również wywoływana podczas ładowania klasy. Wartości on i warning wybierają WARNING, verbose wybiera FINE, debug wybiera ALL, dowolna nazwa java.util.logging.Level, taka jak SEVERE, jest akceptowana, a nie rozpoznana wartość powoduje powrót do OFF.

WARNING pozwala na przechodzenie ostrzeżeń silnika; FINE, ustawienie verbose, również pozwala na przechodzenie szczegółów odzyskiwania parsera. AsposePdfLogging zmienia tylko poddrzewo loggera org.aspose.pdf. Nie zmienia poziomu loggera głównego, a logger biblioteki nie przekazuje rekordów do obsługi loggera głównego. Jeśli logowanie jest włączone i żaden handler nie jest podłączony do loggera biblioteki, instalowany jest handler konsoli.

// 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

Szybki start

Dodaj zależność do swojego projektu:

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

Poniższy przykład tworzy stronę, dodaje wyróżnienie i wolny tekstowy callout oraz zapisuje dokument:

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");
}

Obsługiwane formaty

Obsługa formatów potwierdzona przez opcje ładowania i zapisywania biblioteki oraz urządzenia renderujące:

FormatRozszerzenieOdczytZapis
PDFpdf✓✓
HTMLhtml✓✓
DOCXdocx✓✓
DOCdoc✓✓
XFDFxfdf✓✓
BMPbmp—✓
GIFgif—✓
JPEGjpeg—✓
TIFFtiff—✓
Texttxt—✓

Open Source i licencjonowanie

Aspose.PDF FOSS dla Java jest wydany na licencji MIT, która zezwala na komercyjne użycie, modyfikację i redystrybucję. Kod źródłowy i tracker zgłoszeń znajdują się pod adresem github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Java. Biblioteka jest przeznaczona dla Java 11 lub nowszego.

Rozpoczęcie

Powiązane zasoby