Робота з анотаціями PDF

Анотації PDF у Aspose.PDF FOSS для C++ представляються базовим класом Annotation та його конкретними підтипами (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation та інші). Кожна сторінка надає свої анотації через Page.Annotations(), який повертає AnnotationCollection. У цьому посібнику розглядаються додавання анотацій до сторінки, їх ітерація та видалення, читання анотацій з існуючого документа, приєднання дій посилань, налаштування вигляду та згладжування анотацій.

Додавання анотацій до сторінки

Створіть конкретний екземпляр анотації, розмістіть його за допомогою Rectangle і додайте до колекції сторінки за допомогою AnnotationCollection.Add(). TextAnnotation представляє коментар у стилі липкої нотатки, прив’язаний до точки на сторінці:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(doc);
    note.Rect(Aspose::Pdf::Rectangle(100.0, 700.0, 200.0, 720.0, false));
    note.Contents("Reviewed and approved");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Annotation.Contents() / Contents(value) отримують і встановлюють текст нотатки, а Annotation.Rect() / Rect(value) позиціонують анотацію на сторінці.

Ітерація та видалення анотацій

AnnotationCollection підтримує підрахунок, індексований доступ, перевірки належності та видалення за значенням або за індексом:

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    std::cout << "Annotation count: " << annotations.Count() << "\n";

    for (int i = 0; i < annotations.Count(); ++i) {
        std::cout << "Contents: " << annotations[i].Contents() << "\n";
    }

    if (annotations.Count() > 0) {
        annotations.Delete(0);   // remove by index
    }
    annotations.Clear();         // remove everything
}

AnnotationCollection.Contains(annotation) і Remove(annotation) працюють з конкретним посиланням на анотацію; Delete(index) видаляє за позицією, а Delete(annotation) видаляє певну анотацію без потреби у її індексі. IsReadOnly() повідомляє, чи можна змінювати колекцію.

Читання анотацій з існуючого документа

Коли документ завантажується, його анотації вже заповнені і їх можна переглянути без додавання чого-небудь. Annotation.AnnotationType() повідомляє підтип (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark та інші):

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    for (int i = 0; i < annotations.Count(); ++i) {
        auto& a = annotations[i];
        if (a.AnnotationType() == Aspose::Pdf::Annotations::AnnotationType::Text) {
            std::cout << "Note: " << a.Contents() << "\n";
        }
    }
}

Порядок анотацій і підтип зберігаються під час збереження/перезавантаження, тому код, який індексує Annotations() після завантаження документа, бачить ту ж послідовність, яка була присутня під час запису файлу.

Анотації посилань та дії

LinkAnnotation прикріплює клікабельну область до сторінки й ініціює PdfAction при активації. NamedAction переходить до попередньо визначеної цілі навігації, JavascriptAction виконує рядок ECMAScript, а SubmitFormAction надсилає дані форми за URL за допомогою FileSpecification:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>
#include <aspose/pdf/annotations/predefined_action.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc;
    auto page = doc.Pages().Add();

    Aspose::Pdf::Annotations::LinkAnnotation link(
        page, Aspose::Pdf::Rectangle(0.0, 0.0, 100.0, 20.0, false));
    link.Action(Aspose::Pdf::Annotations::NamedAction(
        Aspose::Pdf::Annotations::PredefinedAction::LastPage));

    page.Annotations().Add(link);
    doc.Save("linked.pdf");
}

LinkAnnotation.Action(value) приймає будь-який підтип PdfAction і клонує його всередині, тож анотація зберігає свою копію дії. LinkAnnotation.Destination() / Destination(value) встановлюють явну ціль навігації замість дії, а Highlighting() / Highlighting(value) керують візуальним відгуком, який показується під час натискання посилання.

Вигляд анотації: межа, прапорці та колір

Кожен Annotation надає Border, бітове поле AnnotationFlags і Color, що використовується для відображення його вигляду:

#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/color.hpp>

// 'note' is an existing Annotation reference, e.g. from AnnotationCollection.
note.Border().Width(2);
note.Border().Style(Aspose::Pdf::Annotations::BorderStyle::Dashed);
note.Flags(Aspose::Pdf::Annotations::AnnotationFlags::Print);
note.Color(Aspose::Pdf::Color::Red());

Border.Style() приймає BorderStyle::Solid, Dashed, Beveled, Inset або Underline. Border.Effect() додатково підтримує BorderEffect::Cloudy контур з EffectIntensity(), що контролює, наскільки він виражений. AnnotationFlags — це бітове поле — комбінуйте значення, такі як Print, NoZoom, ReadOnly і LockedContents, щоб керувати тим, як анотація поводиться у переглядачі, не змінюючи її видимого вмісту.

Згортання анотацій

Одинарну анотацію можна згортати — об’єднати її з вмістом сторінки та зробити неінтерактивною — шляхом прямого виклику Annotation.Flatten():

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();
    for (int i = 0; i < annotations.Count(); ++i) {
        annotations[i].Flatten();
    }
    doc.Save("flattened.pdf");
}

Для операцій над анотаціями у всьому документі PdfAnnotationEditor слідує спільному шаблону Facade, який використовується по всій API: прив’язати вихідний документ за допомогою BindPdf(), застосувати одну або кілька операцій над анотаціями, а потім записати результат за допомогою Save():

#include <aspose/pdf/facades/pdf_annotation_editor.hpp>

int main() {
    Aspose::Pdf::Facades::PdfAnnotationEditor editor;
    editor.BindPdf("annotated.pdf");
    editor.FlatteningAnnotations();
    editor.Save("flattened.pdf");
}

PdfAnnotationEditor.DeleteAnnotations() видаляє всі анотації з прив’язаного документу; DeleteAnnotations(annotType) обмежує видалення однією AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) і ImportAnnotationsFromFdf(fdfFile) завантажують дані анотацій, експортовані іншим переглядачем PDF.

Поради та кращі практики

Завжди додавайте новостворену анотацію до Page.Annotations() перед викликом Document.Save() — анотація, яка ніколи не додана до колекції, не буде записана у вихідний файл.
Використовуйте AnnotationCollection.Contains(annotation) перед викликом Remove(), якщо ви не впевнені, що анотація ще присутня; Remove() повертає false, а не генерує виключення, коли анотація відсутня.
Перевірте Annotation.AnnotationType() перед приведенням типу або розгалуженням на основі поведінки підтипу під час перебору анотацій, завантажених з ненадійного або стороннього PDF-файлу.
Сплющте анотації за допомогою Annotation.Flatten() (або PdfAnnotationEditor.FlatteningAnnotations() для всього документа) перед архівацією документа, щоб оглядачі в інших інструментах бачили той самий вигляд, який ви створили.
AnnotationFlags — це бітове поле; комбінуйте прапорці з базовими цілими значеннями enum, а не припускайте, що одночасно може бути активний лише один прапорець.

Типові проблеми

Проблема	Причина	Виправлення
Анотація не відображається після збереження	Анотація була створена, але ніколи не додана до `Page.Annotations()`	Викличте `page.Annotations().Add(annotation)` перед `doc.Save()`
`Remove()` повертає `false`	Передане посилання на анотацію не відповідає жодному запису, що наразі знаходиться у колекції	Спочатку використайте `Contains()`, або видаліть за індексом за допомогою `Delete(index)`
Неправильний тип анотації після перезавантаження	Код передбачав певний підтип без перевірки `AnnotationType()`	Виконуйте гілку за `Annotation.AnnotationType()` перед тим, як розглядати об’єкт як певний підтип
Дія посилання здається не встановленою після присвоєння	Локальна `PdfAction` вийшла за межі області видимості; `LinkAnnotation.Action()` повертає клоновану копію анотації, а не оригінальний об’єкт	Прочитайте дію назад через `link.Action()`, а не тримайте оригінальну локальну змінну
Операція `PdfAnnotationEditor` не має жодного ефекту	`BindPdf()` не був викликаний, або був викликаний з шляхом, який не існує	Переконайтеся, що `BindPdf()` успішно завершився, перед викликом `FlatteningAnnotations()` або `DeleteAnnotations()`

FAQ

Як додати анотацію у вигляді коментаря до сторінки PDF?

Створіть TextAnnotation з цільовим Document, встановіть його Rect() та Contents(), потім додайте його до page.Annotations() перед збереженням.

Як дізнатися, який тип анотації я розглядаю?

Викличте Annotation.AnnotationType(), який повертає значення enum AnnotationType, наприклад Text, Link, Highlight, FreeText, FileAttachment або Watermark.

Чи може одна анотація містити більше одного прапорця?

Так. AnnotationFlags — це бітове поле (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents та інші), тому кілька прапорців можуть бути об’єднані в одній анотації.

У чому різниця між сплющенням однієї анотації та сплющенням документа?

Annotation.Flatten() об’єднує одну анотацію з вмістом її сторінки. PdfAnnotationEditor.FlatteningAnnotations() (за бажанням обмежений діапазоном сторінок і AnnotationType через перевантаження, що приймає start, end та annotType) сплющує весь прив’язаний документ за один виклик.

Як видалити всі анотації одного типу з документа?

Прив’яжіть документ за допомогою PdfAnnotationEditor.BindPdf(), викличте DeleteAnnotations(annotType) з цільовим AnnotationType, а потім Save() результат.

API Reference Огляд

Клас/Метод	Опис
`Annotation`	Абстрактний базовий клас для всіх підтипів анотацій PDF
`Annotation.Rect()` / `Rect(value)`	Отримати або встановити прямокутник обмеження анотації
`Annotation.Contents()` / `Contents(value)`	Отримати або встановити текстовий вміст анотації
`Annotation.AnnotationType()`	Повертає значення enum `AnnotationType` для цієї анотації
`Annotation.Flags()` / `Flags(value)`	Отримати або встановити `AnnotationFlags` бітове поле
`Annotation.Border()` / `Border(value)`	Отримати або задати `Border` анотації
`Annotation.Color()` / `Color(value)`	Отримати або встановити відображення анотації `Color`
`Annotation.Flatten()`	Об’єднує цю анотацію з вмістом сторінки, роблячи її неінтерактивною
`AnnotationCollection`	Впорядкована колекція анотацій на сторінці, повернена `Page.Annotations()`
`AnnotationCollection.Add(annotation)` / `Add(annotation, considerRotation)`	Додає анотацію до колекції
`AnnotationCollection.Count()`	Повертає кількість анотацій у колекції
`AnnotationCollection.Contains(annotation)`	Повідомляє, чи колекція містить дану анотацію
`AnnotationCollection.Remove(annotation)`	Видаляє конкретну анотацію; повертає `false`, якщо не знайдено
`AnnotationCollection.Delete(index)` / `Delete(annotation)`	Видаляє анотацію за індексом або за посиланням
`AnnotationCollection.Clear()`	Видаляє всі анотації з колекції
`TextAnnotation`	Анотація у стилі нотатки-стікера з `Open()` та `Icon()` (`TextIcon`)
`LinkAnnotation`	Клікабельна область, що передає `PdfAction` через `Action()` / `Action(value)`
`LinkAnnotation.Destination()` / `Destination(value)`	Отримати або встановити явну ціль навігації
`HighlightAnnotation`	Позначає ділянку тексту кольором підсвічування
`FreeTextAnnotation`	Відображає текстовий підпис; налаштовано через `Justification()`, `DefaultAppearanceObject()`, `Callout()`
`CircleAnnotation`	Малює еліпс у прямокутнику анотації
`WatermarkAnnotation`	Накладає анотацію з `Opacity()` / `Opacity(value)` доступом
`WidgetAnnotation`	Анотація вигляду поля форми з `ReadOnly()`, `Required()`, `Exportable()`, `DefaultAppearance()`
`NamedAction`	Попередньо визначена навігаційна дія (`PredefinedAction` enum), яку можна прикріпити до `LinkAnnotation`
`JavascriptAction`	Виконує рядок ECMAScript за допомогою `Script()` / `GetECMAScriptString()`
`SubmitFormAction`	Надсилає дані форми на `FileSpecification` URL за допомогою `Url()` / `Url(value)`
`Border`	Контур анотації з `Width()`, `Style()` (`BorderStyle`), `Effect()` (`BorderEffect`)
`PdfAnnotationEditor`	Фасад для імпорту, модифікації, згладжування та видалення анотацій у всьому документі
`PdfAnnotationEditor.FlatteningAnnotations()`	Згладжує анотації по всьому пов’язаному документу
`PdfAnnotationEditor.DeleteAnnotations(annotType)`	Видаляє всі анотації даного `AnnotationType`
`PdfAnnotationEditor.ImportAnnotationsFromXfdf(xfdfFile)`	Імпортує анотації з файлу XFDF

Дивіться також

Aspose.PDF — Enterprise Documentation