Как сохранить аннотированный PDF с помощью GroupDocs.Annotation для Java
В этом руководстве вы узнаете, как сохранять аннотированные PDF документы программно с помощью GroupDocs.Annotation для Java. Независимо от того, нужно ли вам выделять юридические пункты, добавлять комментарии к обзору или внедрять фигуры в инженерные чертежи, ниже приведённые шаги проведут вас через каждый этап — от настройки Maven до пакетного добавления аннотаций и сохранения конечного файла. К концу вы сможете интегрировать надёжные возможности аннотирования PDF в любое Java‑приложение.
Быстрые ответы
- Какова основная цель GroupDocs.Annotation?
Программно создавать, редактировать и сохранять аннотированные PDF документы в Java‑приложениях. - Какой Maven‑артефакт мне нужен?
com.groupdocs:groupdocs-annotation(см. раздел зависимость Maven). - Могу ли я добавить более одной аннотации за раз?
Да — вы можете добавлять несколько аннотаций за одну операцию, что снижает нагрузку ввода‑вывода. - Как инициализировать аннотатор?
Используйте шаблон initialize annotator, показанный в руководстве; он загружает PDF и подготавливает API для задач аннотирования. - Каковы ключевые рекомендации по лучшим практикам?
Следуйте чек‑листу annotation best practices для управления памятью, пакетной обработки и оптимального размера файла.
Что такое «аннотировать PDF»?
GroupDocs.Annotation — это Java‑библиотека, позволяющая встраивать визуальные заметки — выделения, комментарии, фигуры и штампы — непосредственно в PDF‑файл. Библиотека абстрагирует низкоуровневую работу с PDF, чтобы вы могли сосредоточиться на бизнес‑логике, а не на внутренностях PDF. Она поддерживает широкий спектр типов аннотаций, предоставляет потоковые API для больших документов и легко интегрируется в существующие Java‑проекты, являясь универсальным решением для любых PDF‑ориентированных процессов.
Почему использовать GroupDocs.Annotation для Java?
GroupDocs.Annotation предлагает комплексный набор функций, упрощающих задачи аннотирования PDF при высокой производительности и масштабируемости. Библиотека работает на любой операционной системе, поддерживающей Java, обрабатывает документы до 500 МБ без полной загрузки файла в память и включает более 15 встроенных типов аннотаций. Ее API разработан для разработчиков, позволяя добавлять, редактировать и удалять аннотации всего несколькими строками кода, а также предоставляет гибкие варианты лицензирования для пробного и производственного использования.
- Cross‑platform support – работает на Windows, Linux и macOS, покрывая 100 % совместимых с Java сред.
- Rich annotation types – более 15 встроенных типов, включая текст, область, эллипс и пользовательские штампы.
- No external PDF editors required – все операции выполняются внутри вашего Java‑кода, исключая сторонние зависимости.
- Enterprise‑grade scalability – может обрабатывать PDF до 500 МБ и работать с документами в сотни страниц без загрузки всего файла в память, благодаря потоковым API.
Предварительные требования
- Java 8 или новее (рекомендуется JDK 11 или более поздняя версия).
- Maven для управления зависимостями.
- IDE, например IntelliJ IDEA или Eclipse.
- Базовое знакомство с коллекциями Java и обработкой исключений.
Зависимость Maven GroupDocs
Add the GroupDocs repository and the annotation library to your 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>
Приобретение лицензии
- Free trial – скачайте 30‑дневную пробную версию для оценки API.
- Temporary license – запросите 7‑дневный ключ оценки для полного доступа к функциям.
- Production license – приобретите бессрочную лицензию для неограниченного развертывания.
Как инициализировать аннотатор в Java
Annotator — основной класс GroupDocs.Annotation, который загружает PDF и предоставляет методы для создания, редактирования и сохранения аннотаций. Правильная инициализация — первый шаг к надёжному рабочему процессу, а использование try‑with‑resources гарантирует автоматическое освобождение нативных ресурсов. Вы создаёте экземпляр, передавая путь к файлу (и при необходимости пароль для защищённых PDF) в конструктор, после чего аннотатор готов к дальнейшим операциям.
import com.groupdocs.annotation.Annotator;
public class Feature1 {
public void loadAnnotator(String fileName) {
try (final Annotator annotator = new Annotator(fileName)) {
// Ready to use!
}
}
}
Функция 1: загрузка и инициализация аннотатора
This feature demonstrates creating an Annotator instance with a file path, optionally passing a password for protected PDFs.
import com.groupdocs.annotation.Annotator;
public class Feature1 {
public void loadAnnotator(String fileName) {
try (final Annotator annotator = new Annotator(fileName)) {
// Annotator initialized and ready.
}
}
}
Как создавать аннотации
Creating an annotation involves instantiating a specific annotation model, configuring its properties, and adding it to the annotator’s collection.
Функция 2: создание AreaAnnotation
An AreaAnnotation represents a rectangular highlight region on a PDF page. It is useful for marking sections of text or images that require attention.
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;
}
}
Функция 3: создание EllipseAnnotation
An EllipseAnnotation defines a circular or oval shape that can be placed on a page to emphasize logos, diagrams, or any other visual element.
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;
}
}
Как добавить несколько аннотаций
The addAnnotations method allows you to add a collection of annotation objects to the document in a single call, which improves performance by reducing file‑system writes and memory churn. By batching annotations you minimize I/O operations and keep the JVM heap usage low, especially when working with large PDFs.
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);
}
}
Как сохранить аннотированный PDF
SaveOptions lets you specify which annotation types and output settings to apply when persisting the PDF. Load your PDF, add the desired annotations, and then call the save method with a SaveOptions object that specifies which annotation types to persist. This single‑step operation writes the changes back to disk while preserving the original document structure.
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);
}
}
Лучшие практики аннотирования для Java
- Use try‑with‑resources для автоматического закрытия
Annotatorи освобождения нативных ресурсов. - Batch add annotations (как показано в Функции 4) для минимизации нагрузки ввода‑вывода.
- Specify only needed annotation types в
SaveOptions, чтобы контролировать размер выходного файла. - Release large documents из памяти после сохранения, чтобы избежать утечек; вызовите
annotator.dispose()по завершении.
Практические применения
- Legal document review – выделяйте пункты, прикрепляйте комментарии и отслеживайте изменения рецензентов.
- Educational resources – аннотируйте учебники или слайды лекций для совместных учебных групп.
- Technical manuals – внедряйте заметки, предупреждения и метки ревизий непосредственно в инженерные чертежи.
Соображения по производительности
- Ограничьте одновременные операции аннотирования PDF более 300 МБ, чтобы избежать нагрузки на кучу.
- Используйте рекомендованные annotation best practices, чтобы удерживать использование памяти ниже 200 МБ для типовых корпоративных нагрузок.
- Профилируйте приложение с помощью Java Flight Recorder или VisualVM, если замечаете всплески задержек.
Распространённые проблемы и решения
| Проблема | Решение |
|---|---|
| OutOfMemoryError при загрузке больших PDF | Загрузите документ в режиме потоковой передачи (new Annotator(stream)) или увеличьте размер кучи JVM (-Xmx2g). |
| Аннотации не отображаются после сохранения | Убедитесь, что SaveOptions включает правильные значения перечисления AnnotationType. |
| Ошибки лицензии | Проверьте, что путь к файлу лицензии правильный и версия лицензии соответствует версии библиотеки. |
Часто задаваемые вопросы
Q: Могу ли я добавить текстовые комментарии помимо фигур?
A: Да, GroupDocs.Annotation поддерживает типы TextAnnotation и CommentAnnotation — создайте соответствующую модель и добавьте её в коллекцию аннотатора.
Q: Можно ли редактировать существующую аннотацию?
A: Абсолютно. Получите аннотацию по её ID, измените свойства и вызовите annotator.update(updatedAnnotation).
Q: Как удалить аннотацию, которая больше не нужна?
A: Используйте annotator.delete(annotationId) для удаления конкретной аннотации или annotator.clear(pageNumber) для очистки всех аннотаций на странице.
Q: Работает ли библиотека с PDF, защищёнными паролем?
A: Да. Передайте пароль при создании экземпляра Annotator: new Annotator(filePath, password).
Q: Какая версия Java требуется?
A: Библиотека совместима с Java 8 и новее; мы рекомендуем последнюю LTS‑версию (Java 17) для оптимальной производительности и безопасности.
Последнее обновление: 2026-10-11
Тестировано с: GroupDocs.Annotation 25.2
Автор: GroupDocs