Анотації та форми

Анотації та форми

Aspose.PDF FOSS для .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, приведiть анотацію до 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 реалізує шаблон відвідувача, щоб ви могли фільтрувати анотації за типом без ручного приведення типу.

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 та іменовані дії.
• Викликайте Flatten() перед розповсюдженням PDF, якщо ви хочете, щоб анотації відображалися у неінтерактивних переглядачах.
• Отримуйте доступ до полів форми через Document.Form.Fields, а не перебираючи анотації сторінок — колекція форм обробляє групування полів між сторінками.
• Збережіть і знову відкрийте документ, щоб перевірити точність передачі анотацій у обох напрямках, особливо для користувацьких дій.

Поширені проблеми

ЧаПи

Як додати гіперпосилання до сторінки 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