Как аннотировать PDF с помощью GroupDocs.Annotation для Java

Улучшение Java‑приложений возможностями аннотирования документов — мощный способ повысить сотрудничество, соответствие требованиям и удобство использования. В этом руководстве вы узнаете how to annotate PDF файлы с помощью GroupDocs.Annotation для Java, от настройки зависимости Maven до добавления нескольких аннотаций и соблюдения лучших практик аннотирования. Давайте пройдем каждый шаг, чтобы вы могли уверенно интегрировать эту функцию в свои проекты.

Быстрые ответы

Какова основная цель GroupDocs.Annotation?
Для программного создания, редактирования и save annotated PDF документов в Java‑приложениях.
Какой Maven‑артефакт мне нужен?
com.groupdocs:groupdocs-annotation (см. раздел Maven dependency).
Можно ли добавить более одной аннотации за раз?
Да — вы можете add multiple annotations в одной операции.
Как инициализировать аннотатор?
Используйте шаблон initialize annotator, показанный в руководстве.
Каковы ключевые рекомендации по лучшим практикам?
Следуйте чек‑листу annotation best practices для управления памятью и производительностью.

Что такое “how to annotate PDF”?

Аннотирование PDF означает сохранение визуальных заметок — выделений, комментариев, фигур и других разметок — непосредственно в файл, чтобы любой, открывающий документ, мог увидеть изменения. GroupDocs.Annotation предоставляет простой API для выполнения этой задачи программно.

Почему использовать GroupDocs.Annotation для Java?

Cross‑platform support – работает на любой ОС, где запущен Java.
Rich annotation types – от простых выделений до сложных фигур, таких как эллипсы.
No external PDF editors required – все операции выполняются внутри вашего Java‑кода.
Scalable for enterprise – подходит для юридических, образовательных и технических рабочих процессов с документацией.

Предварительные требования

Java SDK (JDK 8 или новее), установленный на вашем компьютере.
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: Скачайте пробную версию для тестирования GroupDocs.Annotation.
Temporary License: Получите временную лицензию для полного доступа во время оценки.
Purchase: Приобретите полную лицензию для использования в продакшене.

Инициализация аннотатора Java

Первый шаг — initialize the annotator с документом, с которым вы хотите работать. Ниже приведён базовый шаблон инициализации:

import com.groupdocs.annotation.Annotator;

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

Функция 1: Загрузка и инициализация аннотатора

Эта функция демонстрирует инициализацию Annotator с путем к файлу документа, настройку вашего Java‑приложения для задач аннотирования.

import com.groupdocs.annotation.Annotator;

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

Создание аннотаций

Функция 2: Создание Area Annotation

Area annotations позволяют выделять прямоугольные области. Следуйте этим шагам, чтобы создать одну:

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: Создание Ellipse Annotation

Ellipse annotations идеально подходят для круглых или овальных выделений.

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

Добавление нескольких аннотаций

Вы можете add multiple annotations в одном вызове, что повышает производительность и делает ваш код аккуратным.

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

Теперь, когда ваши аннотации добавлены, вы save annotated PDF только с нужными типами аннотаций.

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 (как показано в Feature 4) для снижения нагрузки ввода‑вывода.
Specify only needed annotation types в SaveOptions, чтобы размер файла оставался небольшим.
Release large documents из памяти после сохранения, чтобы избежать утечек.

Практические применения

Legal Document Review: Выделяйте пункты и прикрепляйте комментарии для юристов.
Educational Resources: Аннотируйте учебники для учебных групп.
Technical Manuals: Помечайте инженерные чертежи заметками и предупреждениями.

Соображения по производительности

Ограничьте одновременное аннотирование очень больших PDF.
Используйте рекомендованные annotation best practices для эффективного управления памятью.
Профилируйте приложение с помощью Java Flight Recorder, если замечаете замедления.

Распространённые проблемы и решения

Проблема	Решение
OutOfMemoryError при загрузке больших PDF	Загружайте документ в режиме потоковой передачи или увеличьте размер кучи JVM.
Аннотации не появляются после сохранения	Убедитесь, что `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‑версию для лучшей производительности.

Заключение

Теперь у вас есть полное решение от начала до конца для how to annotate PDF файлов с помощью GroupDocs.Annotation для Java. Следуя приведённым выше шагам — настройке Maven‑зависимости, инициализации аннотатора, созданию и добавлению нескольких аннотаций, а также применению лучших практик аннотирования — вы сможете обогатить любое Java‑приложение мощными возможностями разметки документов.

Последнее обновление: 2026-03-24
Тестировано с: GroupDocs.Annotation 25.2
Автор: GroupDocs