Introducción

Las anotaciones PDF cubren una amplia gama de elementos interactivos y visuales superpuestos al contenido de la página: notas adhesivas de texto, hipervínculos, texto resaltado o tachado, formas geométricas, trazos de tinta, archivos adjuntos y sellos de aprobación. Aspose.PDF FOSS para C++ representa cada una de ellas como una subclase concreta de Annotation, de modo que el código que recorre las anotaciones de una página puede trabajar genéricamente contra la clase base mientras aún accede a miembros específicos del subtipo — como Icon() en un TextAnnotation o Action() en un LinkAnnotation — cuando sea necesario.

El enum Annotations::AnnotationType de la biblioteca enumera los subtipos que reconoce: 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 y varios más. Cada valor se asigna a una clase concreta — CircleAnnotation, SquareAnnotation, PolygonAnnotation, PolylineAnnotation y LineAnnotation para marcas de forma; FreeTextAnnotation y InkAnnotation para texto libre y trazos dibujados; FileAttachmentAnnotation, SoundAnnotation, MovieAnnotation, ScreenAnnotation y RichMediaAnnotation para contenido incrustado; y WidgetAnnotation para apariencias de campos AcroForm.

Esta publicación cubre los API base Annotation y AnnotationCollection, añadiendo notas de texto y enlaces, detectando tipos de anotación al cargar un documento existente, y leyendo o actualizando metadatos de marcado y sellos. Aspose.PDF FOSS para C++ es una biblioteca C++20 sin dependencias en tiempo de ejecución más allá de la biblioteca estándar; los encabezados se incluyen directamente desde el directorio aspose/pdf/annotations/ y la biblioteca se compila como un objetivo de CMake.

Qué incluye

Annotation y AnnotationCollection

Annotation es la clase base para cada subtipo de anotación. Expone propiedades compartidas: Rect() / Rect(value) para el rectángulo delimitador de la anotación, Contents() para el texto asociado, Name(), Color(), Flags() (una máscara de bits AnnotationFlags — Print, Hidden, Invisible, NoZoom, ReadOnly, entre otros), Border(), Width() / Height(), AnnotationType() y PageIndex(). AnnotationCollection contiene las anotaciones de una sola página y se accede mediante 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 también expone Add(annotation), Add(annotation, considerRotation), Delete(index), Delete(annotation), Clear(), Remove(annotation), Contains(annotation) y IsReadOnly().

Notas de texto con TextAnnotation

TextAnnotation representa el conocido comentario de nota adhesiva. Además de los miembros base de Annotation, añade Open() / Open(value) para controlar si la nota aparece expandida, y Icon() / Icon(value) (un valor TextIcon como Note, Comment, Key, Help o Check) para elegir el glifo del ícono.

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

Enlaces y acciones con LinkAnnotation

LinkAnnotation adjunta una región clicable a una página. Se construye a partir de la Page propietaria y un Rectangle, y su comportamiento se establece con Action(value) — cualquier subclase de PdfAction, incluyendo NamedAction (navegación predefinida como PredefinedAction::LastPage), GoToAction, GoToURIAction o JavascriptAction. Destination() lee el objetivo IAppointment del enlace, y Highlighting() / Highlighting(value) define el HighlightingMode (None, Invert, Outline, Push, Toggle) que se aplica cuando el enlace se activa.

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

Detección de tipos de anotación al cargar

Cuando se abre un documento, las anotaciones existentes ya están pobladas en la AnnotationCollection de cada página, y AnnotationType() identifica qué subtipo concreto representa cada entrada. Esto permite que el código llamador ramifique según el valor del enum sin saber de antemano qué tipos de anotación contiene un PDF determinado.

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

Metadatos de anotación de marcado

MarkupAnnotation es la base para anotaciones que transportan metadatos del revisor: Title() (el autor), Subject(), RichText() para texto de comentario con formato, y Opacity() para la fusión con el contenido de la página. InReplyTo() y Popup() conectan una anotación de marcado con el hilo de comentarios al que pertenece, y ClearState() / SetReviewState(state, userName) gestionan su estado de revisión. HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation y SquigglyAnnotation son subtipos de marcado posicionados sobre el texto; su base compartida TextMarkupAnnotation añade QuadPoints() para definir las regiones cuadriláteras cubiertas y GetMarkedText() para leer el texto subyacente.

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

Anotaciones de sello con StampAnnotation

StampAnnotation coloca un sello predefinido o personalizado en una página. Icon() / Icon(value) selecciona un valor StampIcon — Approved, Draft, Confidential, Final, Expired, NotApproved, ForComment, TopSecret, entre otros — y Image() / Image(value) proporciona los bytes de imagen sin procesar para una apariencia de sello personalizada en lugar de un ícono 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);
    }
}

Inicio rápido

Añade la biblioteca como subdirectorio de CMake y enlaza contra el objetivo aspose_pdf_foss:

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

Abra un documento, añada una nota de texto y recupere el recuento de anotaciones:

#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 compatibles

FormatoExtensiónLeerEscribir
BMP.bmp—✓
JPEG.jpg—✓
TIFF.tiff—✓
Text.txt—✓
SVG.svg✓—

El soporte de formato se aplica al renderizado de página y a las opciones de carga a nivel de documento; estas entradas reflejan rutas de exportación confirmadas (BmpDevice, JpegDevice, TiffDevice, TextDevice) e importación (SvgLoadOptions) en lugar de la serialización específica de anotaciones.

Código abierto y licencias

Aspose.PDF FOSS para C++ se publica bajo la licencia MIT. El código fuente está disponible en https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp, y la biblioteca puede usarse en proyectos comerciales y de código abierto sin tarifas de licencia.

Primeros pasos

Recursos relacionados