Jak zapisać oznaczony PDF przy użyciu GroupDocs.Annotation dla Javy

W tym samouczku odkryjesz jak zapisać oznaczone PDF dokumenty programowo przy użyciu GroupDocs.Annotation dla Javy. Niezależnie od tego, czy musisz podświetlić klauzule prawne, dodać komentarze recenzentów, czy osadzić kształty w rysunkach technicznych, poniższe kroki przeprowadzą Cię przez każdy etap — od konfiguracji Maven po wsadowe dodawanie adnotacji i zapisywanie finalnego pliku. Po zakończeniu będziesz w stanie zintegrować solidne możliwości adnotacji PDF z dowolną aplikacją Java.

Szybkie odpowiedzi

  • Jaki jest główny cel GroupDocs.Annotation?
    Aby programowo tworzyć, edytować i zapisywać oznaczone PDF dokumenty w aplikacjach Java.
  • Który artefakt Maven jest potrzebny?
    com.groupdocs:groupdocs-annotation (zobacz sekcję Maven dependency).
  • Czy mogę dodać więcej niż jedną adnotację jednocześnie?
    Tak – możesz dodać wiele adnotacji w jednej operacji, co zmniejsza obciążenie I/O.
  • Jak zainicjalizować annotator?
    Użyj wzorca initialize annotator pokazanego w samouczku; ładuje on PDF i przygotowuje API do zadań adnotacji.
  • Jakie są kluczowe wskazówki najlepszych praktyk?
    Postępuj zgodnie z listą kontrolną annotation best practices dotyczącą zarządzania pamięcią, przetwarzania wsadowego i optymalnego rozmiaru pliku.

Co to jest „jak adnotować PDF”?

GroupDocs.Annotation jest biblioteką Java, która pozwala osadzać wizualne notatki — podświetlenia, komentarze, kształty i pieczątki — bezpośrednio w pliku PDF. Biblioteka abstrahuje niskopoziomową manipulację PDF, dzięki czemu możesz skupić się na logice biznesowej, a nie na wewnętrznych szczegółach PDF. Obsługuje szeroką gamę typów adnotacji, udostępnia API strumieniowe dla dużych dokumentów i łatwo integruje się z istniejącymi projektami Java, co czyni ją wszechstronnym rozwiązaniem dla każdego przepływu pracy opartego na PDF.

Dlaczego używać GroupDocs.Annotation dla Javy?

GroupDocs.Annotation oferuje kompleksowy zestaw funkcji, które upraszczają zadania adnotacji PDF, jednocześnie zapewniając wysoką wydajność i skalowalność. Biblioteka działa na każdym systemie operacyjnym obsługującym Javę, radzi sobie z dokumentami do 500 MB bez ładowania całego pliku do pamięci i zawiera ponad 15 wbudowanych typów adnotacji. Jej API jest zaprojektowane z myślą o deweloperach, umożliwiając dodawanie, edytowanie i usuwanie adnotacji kilkoma liniami kodu, a także oferuje solidne opcje licencjonowania zarówno w wersji próbnej, jak i produkcyjnej.

  • Wsparcie wieloplatformowe – działa na Windows, Linux i macOS, obejmując 100 % środowisk kompatybilnych z Javą.
  • Bogate typy adnotacji – ponad 15 wbudowanych typów, w tym tekst, obszar, elipsa i niestandardowe pieczątki.
  • Brak wymogu zewnętrznych edytorów PDF – wszystkie operacje odbywają się w kodzie Java, eliminując zależności od stron trzecich.
  • Skalowalność klasy korporacyjnej – może przetwarzać PDFy do 500 MB i obsługiwać dokumenty o setkach stron bez ładowania całego pliku do pamięci, dzięki API strumieniowemu.

Prerequisites

  • Java 8 lub nowsza (zalecany JDK 11 lub nowszy).
  • Maven do zarządzania zależnościami.
  • IDE, np. IntelliJ IDEA lub Eclipse.
  • Podstawowa znajomość kolekcji Java i obsługi wyjątków.

Zależność Maven GroupDocs

Dodaj repozytorium GroupDocs oraz bibliotekę adnotacji do swojego pom.xml:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/annotation/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-annotation</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

Uzyskanie licencji

  1. Darmowa wersja próbna – pobierz 30‑dniową wersję próbną, aby ocenić API.
  2. Licencja tymczasowa – zamów 7‑dniowy klucz ewaluacyjny, aby uzyskać pełny dostęp do funkcji.
  3. Licencja produkcyjna – zakup licencję wieczystą na nieograniczone wdrożenia.

Jak zainicjalizować annotator w Javie

Annotator jest podstawową klasą GroupDocs.Annotation, która ładuje PDF i udostępnia metody do tworzenia, edytowania i zapisywania adnotacji. Poprawna inicjalizacja to pierwszy krok w kierunku niezawodnego przepływu pracy, a użycie try‑with‑resources zapewnia automatyczne zwalnianie zasobów natywnych. Tworzysz instancję, przekazując ścieżkę do pliku (opcjonalnie hasło do zabezpieczonych PDFów) do konstruktora, po czym annotator jest gotowy do dalszych operacji.

import com.groupdocs.annotation.Annotator;

public class Feature1 {
    public void loadAnnotator(String fileName) {
        try (final Annotator annotator = new Annotator(fileName)) {
            // Ready to use!
        }
    }
}

Funkcja 1: ładowanie i inicjalizacja annotatora

Ta funkcja demonstruje tworzenie instancji Annotator z podaniem ścieżki do pliku, opcjonalnie przekazując hasło do zabezpieczonych PDFów.

import com.groupdocs.annotation.Annotator;

public class Feature1 {
    public void loadAnnotator(String fileName) {
        try (final Annotator annotator = new Annotator(fileName)) {
            // Annotator initialized and ready.
        }
    }
}

Jak tworzyć adnotacje

Tworzenie adnotacji polega na zainstancjonowaniu konkretnego modelu adnotacji, skonfigurowaniu jego właściwości i dodaniu go do kolekcji annotatora.

Funkcja 2: tworzenie adnotacji obszaru

AreaAnnotation reprezentuje prostokątny obszar podświetlenia na stronie PDF. Jest przydatna do oznaczania fragmentów tekstu lub obrazów wymagających uwagi.

import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;

public class Feature2 {
    public AreaAnnotation createAreaAnnotation() {
        AreaAnnotation area = new AreaAnnotation();
        area.setBox(new Rectangle(100, 100, 100, 100));
        area.setBackgroundColor(65535);
        area.setPageNumber(1);

        return area;
    }
}

Funkcja 3: tworzenie adnotacji elipsy

EllipseAnnotation definiuje kształt koła lub owalu, który można umieścić na stronie w celu podkreślenia logo, diagramu lub innego elementu wizualnego.

import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;

public class Feature3 {
    public EllipseAnnotation createEllipseAnnotation() {
        EllipseAnnotation ellipse = new EllipseAnnotation();
        ellipse.setBox(new Rectangle(100, 100, 100, 100));
        ellipse.setBackgroundColor(123456);
        ellipse.setPageNumber(2);

        return ellipse;
    }
}

Jak dodać wiele adnotacji

Metoda addAnnotations umożliwia dodanie kolekcji obiektów adnotacji do dokumentu w jednym wywołaniu, co poprawia wydajność poprzez redukcję zapisów do systemu plików i obciążenia pamięci. Grupując adnotacje, minimalizujesz operacje I/O i utrzymujesz niskie zużycie sterty JVM, szczególnie przy pracy z dużymi PDFami.

import com.groupdocs.annotation.Annotator;
import java.util.ArrayList;
import java.util.List;
import com.groupdocs.annotation.models.AnnotationBase;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;

public class Feature4 {
    public void addAnnotations(Annotator annotator) {
        AreaAnnotation area = new AreaAnnotation();
        area.setBox(new Rectangle(100, 100, 100, 100));
        area.setBackgroundColor(65535);
        area.setPageNumber(1);

        EllipseAnnotation ellipse = new EllipseAnnotation();
        ellipse.setBox(new Rectangle(100, 100, 100, 100));
        ellipse.setBackgroundColor(123456);
        ellipse.setPageNumber(2);

        List<AnnotationBase> annotations = new ArrayList<>();
        annotations.add(area);
        annotations.add(ellipse);

        annotator.add(annotations);
    }
}

Jak zapisać oznaczony PDF

SaveOptions pozwala określić, które typy adnotacji i ustawienia wyjściowe zastosować przy zapisywaniu PDF. Załaduj swój PDF, dodaj pożądane adnotacje, a następnie wywołaj metodę save z obiektem SaveOptions, który określa, które typy adnotacji mają zostać zachowane. Ta jednoczesna operacja zapisuje zmiany na dysku, zachowując pierwotną strukturę dokumentu.

public class Feature5 {
    public String getOutputPath(String fileName) {
        return "YOUR_OUTPUT_DIRECTORY" + "/filtered_output.pdf";
    public void saveAnnotatedDocument(Annotator annotator, String outputPath) {
        SaveOptions saveOptions = new SaveOptions();
        saveOptions.setAnnotationTypes(AnnotationType.ELLIPSE);

        annotator.save(outputPath, saveOptions);
    }
}

Najlepsze praktyki adnotacji dla Javy

  • Używaj try‑with‑resources aby automatycznie zamykać Annotator i zwalniać zasoby natywne.
  • Dodawaj adnotacje wsadowo (jak pokazano w Funkcji 4), aby zminimalizować obciążenie I/O.
  • Określ tylko potrzebne typy adnotacji w SaveOptions, aby utrzymać rozmiar pliku wyjściowego pod kontrolą.
  • Zwolnij duże dokumenty z pamięci po zapisaniu, aby uniknąć wycieków; wywołaj annotator.dispose() po zakończeniu.

Praktyczne zastosowania

  • Przegląd dokumentów prawnych – podświetlaj klauzule, dołączaj komentarze i śledź zmiany recenzentów.
  • Zasoby edukacyjne – adnotuj podręczniki lub slajdy wykładowe dla grup współpracujących przy nauce.
  • Podręczniki techniczne – osadzaj notatki, ostrzeżenia i oznaczenia rewizji bezpośrednio na rysunkach technicznych.

Rozważania dotyczące wydajności

  • Ogranicz jednoczesne operacje adnotacji na PDFach większych niż 300 MB, aby uniknąć obciążenia sterty.
  • Używaj zalecanych annotation best practices, aby utrzymać zużycie pamięci poniżej 200 MB przy typowych obciążeniach korporacyjnych.
  • Profiluj aplikację przy użyciu Java Flight Recorder lub VisualVM, jeśli zauważysz skoki opóźnień.

Typowe problemy i rozwiązania

ProblemRozwiązanie
OutOfMemoryError przy ładowaniu dużych PDFówZaładuj dokument w trybie strumieniowym (new Annotator(stream)) lub zwiększ stertę JVM (-Xmx2g).
Adnotacje nie pojawiają się po zapisaniuUpewnij się, że SaveOptions zawiera prawidłowe wartości wyliczenia AnnotationType.
Błędy licencjiSprawdź, czy ścieżka do pliku licencji jest poprawna oraz czy wersja licencji odpowiada wersji biblioteki.

Najczęściej zadawane pytania

P: Czy mogę dodać komentarze tekstowe oprócz kształtów?
A: Tak, GroupDocs.Annotation obsługuje typy TextAnnotation i CommentAnnotation — utwórz odpowiedni model i dodaj go do kolekcji annotatora.

P: Czy można edytować istniejącą adnotację?
A: Oczywiście. Pobierz adnotację po jej ID, zmodyfikuj jej właściwości i wywołaj annotator.update(updatedAnnotation).

P: Jak usunąć adnotację, której już nie potrzebuję?
A: Użyj annotator.delete(annotationId), aby usunąć konkretną adnotację, lub annotator.clear(pageNumber), aby wyczyścić wszystkie adnotacje na stronie.

P: Czy biblioteka działa z PDF‑ami zabezpieczonymi hasłem?
A: Tak. Podaj hasło przy tworzeniu instancji Annotator: new Annotator(filePath, password).

P: Jakiej wersji Javy wymaga biblioteka?
A: Biblioteka jest kompatybilna z Javą 8 i nowszą; zalecamy najnowszą wersję LTS (Java 17) dla optymalnej wydajności i bezpieczeństwa.


Ostatnia aktualizacja: 2026-10-11
Testowano z: GroupDocs.Annotation 25.2
Autor: GroupDocs


Powiązane samouczki