Аннотации и формы

Аннотации и формы

Aspose.PDF FOSS for .NET дает вам полный доступ к чтению/записи аннотаций PDF и интерактивных полей AcroForm. Основной точкой входа для аннотаций является Page.Annotations (AnnotationCollection), в то время как поля формы доступны через Document.Form. Обе подсистемы работают полностью в памяти и не требуют лицензионного ключа.

Добавление аннотаций

AnnotationCollection предоставляет типизированные вспомогательные методы для каждого стандартного типа аннотации. Каждый метод принимает Rectangle, определяющий положение аннотации на странице, плюс параметры, специфичные для типа.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// Text (sticky-note) annotation
page.Annotations.AddTextAnnotation(
    new Rectangle(72, 720, 200, 740),
    contents: "Review this paragraph",
    title: "Editor",
    open: true);

// Highlight annotation
page.Annotations.AddHighlightAnnotation(
    new Rectangle(72, 680, 300, 700),
    quadPoints: null,
    color: new double[] { 1, 1, 0 });

// Free-text annotation (rendered directly on the page)
page.Annotations.AddFreeTextAnnotation(
    new Rectangle(72, 640, 350, 660),
    contents: "Inline note",
    fontName: "Helvetica",
    fontSize: 10,
    color: new double[] { 0, 0, 0 });

using var ms = new MemoryStream();
doc.Save(ms);

Аннотации ссылок и действия

Ссылки объединяют кликаемый прямоугольник с PdfAction. Библиотека поддерживает URI, GoTo, JavaScript, Named и Launch действия.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// URI link
var uriAction = PdfAction.CreateUri("https://aspose.com");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 700, 200, 720), uriAction);

// GoTo link (jump to page 3)
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 660, 200, 680),
    destinationPage: 3,
    destRect: new Rectangle(0, 0, 612, 792));

// JavaScript link
var jsAction = PdfAction.CreateJavaScript("app.alert('Hello');");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 620, 200, 640), jsAction);

doc.Save("links.pdf");

Чтобы прочитать ссылку после открытия сохранённого PDF, приведите аннотацию к типу LinkAnnotation и проверьте её свойство Uri или разрешите словарь действия через PdfAction.Create.

Разметка и аннотации фигур

Разметка аннотаций (выделение, подчеркивание, зачеркивание) помечает существующий текст. Графические аннотации (квадрат, круг, линия, чернила) рисуют геометрию на странице.

var page = doc.Pages[1];

// Underline
page.Annotations.AddUnderlineAnnotation(
    new Rectangle(72, 600, 300, 620),
    quadPoints: null,
    color: new double[] { 1, 0, 0 });

// Square
page.Annotations.AddSquareAnnotation(
    new Rectangle(72, 540, 200, 580),
    borderColor: new double[] { 0, 0, 1 },
    fillColor: null,
    lineWidth: 1.5);

// Line
page.Annotations.AddLineAnnotation(
    new Rectangle(72, 500, 300, 520),
    x1: 72, y1: 510, x2: 300, y2: 510,
    color: new double[] { 0, 0.5, 0 },
    lineWidth: 2);

// Ink (freehand)
page.Annotations.AddInkAnnotation(
    new Rectangle(72, 440, 200, 480),
    inkPaths: new[] { new double[] { 80, 450, 120, 470, 160, 450 } },
    color: new double[] { 0.5, 0, 0.5 },
    lineWidth: 1);

Аннотации штампа

Аннотации штампа накладывают изображение или предопределённый значок на страницу.

var stamp = new StampAnnotation(doc);
// Configure stamp properties, then add to page
page.Annotations.Add(stamp);

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

Вызовите Flatten() для любой аннотации, чтобы зафиксировать её визуальное отображение в потоке содержимого страницы и удалить её из списка интерактивных аннотаций.

foreach (var annot in doc.Pages[1].Annotations)
{
    annot.Flatten();
}

Шаблон посетителя с AnnotationSelector

AnnotationSelector реализует шаблон Visitor, позволяя фильтровать аннотации по типу без ручного приведения типов.

var selector = new AnnotationSelector();
doc.Pages[1].Accept(selector);

// selector.Selected now contains all annotations on page 1
foreach (var annot in selector.Selected)
{
    // Process each annotation by type
}

Передайте экземпляр типизированной аннотации в конструктор, чтобы отфильтровать только этот тип:

var linkFilter = new AnnotationSelector(new LinkAnnotation(page, Rectangle.Empty));
page.Accept(linkFilter);
// linkFilter.Selected contains only LinkAnnotation instances

Интерактивные поля формы

Получайте доступ к полям AcroForm через Document.Form. Класс Form предоставляет операции чтения/записи на уровне полей и поддерживает экспорт в JSON.

using var doc = Document.Open(pdfBytes);

// Enumerate all fields
foreach (var field in doc.Form.Fields)
{
    Console.WriteLine($"{field.FullName}: {field.Value}");
}

Подклассы Field включают TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField, и SignatureField.

Экспорт данных формы в JSON

WidgetAnnotation предоставляет ExportToJson перегрузки для сериализации данных полей в поток или путь к файлу. Необязательный параметр ExportFieldsToJsonOptions управляет форматированием вывода.

using var doc = Document.Open(pdfBytes);
var widget = (WidgetAnnotation)doc.Pages[1].Annotations[1];

using var jsonStream = new MemoryStream();
widget.ExportToJson(jsonStream);

Советы и лучшие практики

• Всегда указывайте явные координаты Rectangle в единицах пользовательского пространства PDF (1/72 дюйма).
• Используйте AddLinkAnnotation с PdfAction для максимальной гибкости — поддерживаются URI, GoTo, JavaScript и Named actions.
• Вызовите Flatten() перед распространением PDF, если вы хотите, чтобы аннотации отображались в неинтерактивных просмотрщиках.
• Получайте доступ к полям формы через Document.Form.Fields, а не перебирая аннотации страниц — коллекция форм обрабатывает группировку полей через страницы.
• Сохраните и откройте документ заново, чтобы проверить точность обратного прохождения аннотаций, особенно для пользовательских действий.

Общие проблемы

FAQ

Как добавить гиперссылку на страницу PDF?

Используйте page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)), чтобы создать кликабельную ссылку URI в указанном прямоугольнике.

Могу ли я прочитать значения полей формы из существующего PDF?

Да. Откройте документ с помощью Document.Open, затем пройдите по Document.Form.Fields и прочитайте свойство Value у каждого Field.

Какие типы аннотаций поддерживает библиотека?

Библиотека поддерживает текст, свободный текст, ссылку, выделение, подчеркивание, зачеркивание, квадрат, круг, линию, чернильную запись, штамп, каретку, вложение файла, звук, полигон, полилинию, виджет, водяной знак и 3D‑аннотации. Все типы доступны через методы‑помощники AnnotationCollection или прямое создание.

Как отфильтровать аннотации по типу?

Используйте AnnotationSelector с типизированной шаблонной аннотацией. Вызовите page.Accept(selector) и проверьте selector.Selected на соответствующие аннотации.

Могу ли я «запечатлеть» только определённые аннотации?

Да. Вызывайте Flatten() для отдельных экземпляров Annotation, а не перебирайте всю коллекцию.

Сводка справки API

См. также

• Aspose.PDF for .NET Enterprise Product