Анотації PDF у C++ — текстові нотатки, посилання, виділення та штампи | File Format Processing Plugins for C# .NET Core

Вступ

Анотації PDF охоплюють широкий спектр інтерактивних та візуальних елементів, накладених поверх вмісту сторінки: липкі текстові нотатки, гіперпосилання, підсвічений або перекреслений текст, геометричні форми, мазки чорнила, прикріплені файли та печатки затвердження. Aspose.PDF FOSS для C++ представляє кожен із них як конкретний підклас Annotation, тому код, що обходить анотації сторінки, може працювати загально щодо базового класу, одночасно отримуючи доступ до членів, специфічних для підтипу — наприклад Icon() у TextAnnotation або Action() у LinkAnnotation — за потреби.

Перерахування Annotations::AnnotationType у бібліотеці перераховує підтипи, які вона розпізнає: Text, Link, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, Popup, FileAttachment, Sound, Movie, Widget, Screen, PrinterMark, Watermark, Redaction, RichMedia та кілька інших. Кожне значення відповідає конкретному класу — CircleAnnotation, SquareAnnotation, PolygonAnnotation, PolylineAnnotation та LineAnnotation для розмітки форм; FreeTextAnnotation і InkAnnotation для вільного тексту та намальованих штрихів; FileAttachmentAnnotation, SoundAnnotation, MovieAnnotation, ScreenAnnotation і RichMediaAnnotation для вбудованого вмісту; та WidgetAnnotation для відображення полів AcroForm.

У цьому дописі розглядаються базові API Annotation та AnnotationCollection, додавання текстових нотаток і посилань, виявлення типів анотацій під час завантаження існуючого документа та читання або оновлення метаданих розмітки та печаток. Aspose.PDF FOSS для C++ — це бібліотека C++20 без залежностей часу виконання, окрім стандартної бібліотеки; заголовки включаються безпосередньо з каталогу aspose/pdf/annotations/, а бібліотека збирається як ціль CMake.

Що включено

Annotation та AnnotationCollection

Annotation — це базовий клас для кожного підтипу анотації. Він надає спільні властивості: Rect() / Rect(value) для обмежувального прямокутника анотації, Contents() для пов’язаного тексту, Name(), Color(), Flags() (бітова маска AnnotationFlags — Print, Hidden, Invisible, NoZoom, ReadOnly та інші), Border(), Width() / Height(), AnnotationType() і PageIndex(). AnnotationCollection містить анотації на одній сторінці і доступний через Page.Annotations().

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("reviewed.pdf");
AnnotationCollection& annots = doc.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";
for (int i = 0; i < annots.Count(); ++i) {
    Annotation& a = annots[i];
    std::cout << "  " << a.Name() << ": " << a.Contents() << "\n";
}

AnnotationCollection також надає Add(annotation), Add(annotation, considerRotation), Delete(index), Delete(annotation), Clear(), Remove(annotation), Contains(annotation) та IsReadOnly().

Текстові нотатки з TextAnnotation

TextAnnotation представляє знайомий коментар у вигляді липкої нотатки. Окрім базових членів Annotation, він додає Open() / Open(value) для керування тим, чи нотатка розгорнута, та Icon() / Icon(value) (значення TextIcon, таке як Note, Comment, Key, Help або Check) для вибору гліфа іконки.

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

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("input.pdf");

TextAnnotation note{doc};
note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
note.Contents("Reviewed by QA");
note.Icon(TextIcon::Comment);
note.Open(true);

doc.Pages()[1].Annotations().Add(note);
doc.Save("annotated.pdf");

Посилання та дії з LinkAnnotation

LinkAnnotation прив’язує клікабельну область до сторінки. Вона створюється з власної Page та Rectangle, а її поведінка задається за допомогою Action(value) — будь-якого підкласу PdfAction, включаючи NamedAction (заздалегідь визначена навігація, наприклад PredefinedAction::LastPage), GoToAction, GoToURIAction або JavascriptAction. Destination() читає ціль IAppointment посилання, а Highlighting() / Highlighting(value) встановлює HighlightingMode (None, Invert, Outline, Push, Toggle), що застосовується під час активації посилання.

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

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

LinkAnnotation link{page, Rectangle{0.0, 0.0, 100.0, 20.0, false}};
link.Action(NamedAction{PredefinedAction::LastPage});
link.Highlighting(HighlightingMode::Push);

page.Annotations().Add(link);

Виявлення типів анотацій при завантаженні

Коли документ відкривається, існуючі анотації вже заповнені в AnnotationCollection кожної сторінки, і AnnotationType() визначає, який конкретний підтип представляє кожен запис. Це дозволяє виклику коду гілкуватися за значенням enum без попереднього знання, які типи анотацій містить даний PDF.

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

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("mixed-annotations.pdf");
auto& annots = doc.Pages()[1].Annotations();

for (int i = 0; i < annots.Count(); ++i) {
    switch (annots[i].AnnotationType()) {
        case AnnotationType::Text:      std::cout << "Text note\n"; break;
        case AnnotationType::Link:      std::cout << "Link\n"; break;
        case AnnotationType::Circle:    std::cout << "Circle shape\n"; break;
        case AnnotationType::Square:    std::cout << "Square shape\n"; break;
        case AnnotationType::Highlight: std::cout << "Highlight\n"; break;
        case AnnotationType::Stamp:     std::cout << "Stamp\n"; break;
        default: break;
    }
}

Метадані розміткових анотацій

MarkupAnnotation — це базовий клас для анотацій, що містять метадані рецензента: Title() (автор), Subject(), RichText() для форматованого тексту коментаря та Opacity() для змішування з вмістом сторінки. InReplyTo() і Popup() пов’язують анотацію розмітки з відповідною гілкою коментарів, а ClearState() / SetReviewState(state, userName) керують її статусом перегляду. HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation і SquigglyAnnotation — це підтипи розмітки, розташовані над текстом; їх спільна база TextMarkupAnnotation додає QuadPoints() для визначення чотирикутних областей та GetMarkedText() для отримання тексту під ними.

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

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* markup = dynamic_cast<MarkupAnnotation*>(&annots[i])) {
        markup->Title("QA Reviewer");
        markup->Subject("Layout issue");
        markup->Opacity(0.6);
    }
}

Анотації-штампи за допомогою StampAnnotation

StampAnnotation розміщує заздалегідь визначений або користувацький штамп на сторінці. Icon() / Icon(value) вибирає значення StampIcon — Approved, Draft, Confidential, Final, Expired, NotApproved, ForComment, TopSecret та інші —, а Image() / Image(value) надає необроблені байти зображення для кастомного вигляду штампа замість вбудованої іконки.

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

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* stamp = dynamic_cast<StampAnnotation*>(&annots[i])) {
        stamp->Icon(StampIcon::Approved);
    }
}

Швидкий старт

Додайте бібліотеку як підкаталог CMake і зв’яжіть її з ціллю aspose_pdf_foss:

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

Відкрийте документ, додайте текстову нотатку та зчитайте кількість анотацій:

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

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

int main() {
    Document doc("input.pdf");

    TextAnnotation note{doc};
    note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
    note.Contents("Reviewed by QA");
    note.Icon(TextIcon::Comment);

    doc.Pages()[1].Annotations().Add(note);
    doc.Save("annotated.pdf");

    std::cout << "Annotations on page 1: "
              << doc.Pages()[1].Annotations().Count() << "\n";
}

Підтримувані формати

Формат	Розширення	Читати	Запис
BMP	.bmp	—	✓
JPEG	.jpg	—	✓
TIFF	.tiff	—	✓
Text	.txt	—	✓
SVG	.svg	✓	—

Підтримка форматів застосовується до рендерингу сторінок та параметрів завантаження на рівні документа; ці записи відображають підтверджені шляхи експорту (BmpDevice, JpegDevice, TiffDevice, TextDevice) і імпорту (SvgLoadOptions), а не специфічну для анотацій серіалізацію.

Відкритий код та ліцензування

Aspose.PDF FOSS для C++ випущено під ліцензією MIT. Вихідний код доступний за адресою https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp, і бібліотеку можна використовувати у комерційних та open-source проектах без ліцензійних платежів.

Початок роботи

Пов’язані ресурси

Aspose.PDF — Enterprise Blog

Вступ#

Що включено#

Annotation та AnnotationCollection#

Текстові нотатки з TextAnnotation#

Посилання та дії з LinkAnnotation#

Виявлення типів анотацій при завантаженні#

Метадані розміткових анотацій#

Анотації-штампи за допомогою StampAnnotation#

Швидкий старт#

Підтримувані формати#

Відкритий код та ліцензування#

Початок роботи#

Пов’язані ресурси#