Introdução

As anotações PDF abrangem uma ampla variedade de elementos interativos e visuais sobrepostos ao conteúdo da página: notas adesivas de texto, hiperlinks, texto destacado ou tachado, formas geométricas, traços de tinta, anexos de arquivos e selos de aprovação. Aspose.PDF FOSS para C++ representa cada um desses como uma subclasse concreta de Annotation, de modo que o código que percorre as anotações de uma página pode operar genericamente contra a classe base enquanto ainda acessa membros específicos de subtipos — como Icon() em um TextAnnotation ou Action() em um LinkAnnotation — quando necessário.

O enum Annotations::AnnotationType da biblioteca enumera os subtipos que reconhece: 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 e vários outros. Cada valor mapeia para uma classe concreta — CircleAnnotation, SquareAnnotation, PolygonAnnotation, PolylineAnnotation e LineAnnotation para marcação de formas; FreeTextAnnotation e InkAnnotation para texto livre e traços desenhados; FileAttachmentAnnotation, SoundAnnotation, MovieAnnotation, ScreenAnnotation e RichMediaAnnotation para conteúdo incorporado; e WidgetAnnotation para aparências de campos AcroForm.

Este post aborda a base API de Annotation e AnnotationCollection, adicionando notas de texto e links, detectando tipos de anotação ao carregar um documento existente e lendo ou atualizando metadados de marcação e selos. Aspose.PDF FOSS para C++ é uma biblioteca C++20 sem dependências em tempo de execução além da biblioteca padrão; os cabeçalhos são incluídos diretamente do diretório aspose/pdf/annotations/ e a biblioteca é compilada como um alvo CMake.

O que está incluído

Annotation e AnnotationCollection

Annotation é a classe base para todo subtipo de anotação. Ela expõe propriedades compartilhadas: Rect() / Rect(value) para o retângulo delimitador da anotação, Contents() para o texto associado, Name(), Color(), Flags() (uma máscara de bits AnnotationFlags — Print, Hidden, Invisible, NoZoom, ReadOnly e outras), Border(), Width() / Height(), AnnotationType() e PageIndex(). AnnotationCollection contém as anotações em uma única página e é acessada através de 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 também expõe Add(annotation), Add(annotation, considerRotation), Delete(index), Delete(annotation), Clear(), Remove(annotation), Contains(annotation) e IsReadOnly().

Notas de Texto com TextAnnotation

TextAnnotation representa o familiar comentário de nota adesiva. Além dos membros base de Annotation, ele adiciona Open() / Open(value) para controlar se a nota aparece expandida, e Icon() / Icon(value) (um valor TextIcon como Note, Comment, Key, Help ou Check) para escolher o glifo do ícone.

#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 anexa uma região clicável a uma página. É construído a partir da Page proprietária e de um Rectangle, e seu comportamento é definido com Action(value) — qualquer subclasse de PdfAction, incluindo NamedAction (navegação predefinida como PredefinedAction::LastPage), GoToAction, GoToURIAction ou JavascriptAction. Destination() lê o alvo IAppointment do link, e Highlighting() / Highlighting(value) define o HighlightingMode (None, Invert, Outline, Push, Toggle) aplicado quando o link é ativado.

#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);

Detectando Tipos de Anotação ao Carregar

Quando um documento é aberto, as anotações existentes já são preenchidas na AnnotationCollection de cada página, e AnnotationType() identifica qual subtipo concreto cada entrada representa. Isso permite que o código chamador faça ramificações com base no valor do enum sem precisar saber antecipadamente quais tipos de anotação um determinado PDF contém.

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

Metadados de Anotação de Marcação

MarkupAnnotation é a base para anotações que carregam metadados do revisor: Title() (o autor), Subject(), RichText() para texto de comentário formatado e Opacity() para mesclar com o conteúdo da página. InReplyTo() e Popup() conectam uma anotação de marcação ao thread de comentários ao qual ela pertence, e ClearState() / SetReviewState(state, userName) gerenciam seu status de revisão. HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation e SquigglyAnnotation são subtipos de marcação posicionados sobre o texto; sua base compartilhada TextMarkupAnnotation adiciona QuadPoints() para definir as regiões quadriláteras cobertas e GetMarkedText() para ler o texto subjacente.

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

Anotações de carimbo com StampAnnotation

StampAnnotation coloca um selo predefinido ou personalizado em uma página. Icon() / Icon(value) seleciona um valor StampIcon — Approved, Draft, Confidential, Final, Expired, NotApproved, ForComment, TopSecret e outros — e Image() / Image(value) fornece bytes de imagem brutos para a aparência de um selo personalizado em vez de um ícone incorporado.

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

Início rápido

Adicione a biblioteca como um subdiretório CMake e vincule ao alvo aspose_pdf_foss:

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

Abra um documento, adicione uma nota de texto e recupere a contagem de anotações:

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

Formatos suportados

FormatoExtensãoLerEscrever
BMP.bmp—✓
JPEG.jpg—✓
TIFF.tiff—✓
Text.txt—✓
SVG.svg✓—

O suporte a formatos aplica-se à renderização de páginas e às opções de carregamento ao nível do documento; essas entradas refletem caminhos de exportação confirmados (BmpDevice, JpegDevice, TiffDevice, TextDevice) e de importação (SvgLoadOptions) em vez de serialização específica de anotações.

Código Aberto & Licenciamento

Aspose.PDF FOSS para C++ é lançado sob a licença MIT. O código-fonte está disponível em https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp, e a biblioteca pode ser usada em projetos comerciais e de código aberto sem taxas de licenciamento.

Começando

Recursos Relacionados