Lavorare con le annotazioni PDF

Le annotazioni PDF in Aspose.PDF FOSS per C++ sono rappresentate dalla classe base Annotation e dalle sue sottoclassi concrete (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation e altre). Ogni pagina espone le sue annotazioni tramite Page.Annotations(), che restituisce un AnnotationCollection. Questa guida copre l’aggiunta di annotazioni a una pagina, l’iterazione e la rimozione di esse, la lettura delle annotazioni da un documento esistente, l’attacco di azioni di collegamento, la personalizzazione dell’aspetto e l’appiattimento delle annotazioni.

Aggiungere annotazioni a una pagina

Crea un’istanza concreta di annotazione, posizionala con un Rectangle e aggiungila alla collezione della pagina con AnnotationCollection.Add(). TextAnnotation rappresenta un commento in stile nota adesiva ancorato a un punto sulla pagina:

#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) ottengono e impostano il testo della nota, e Annotation.Rect() / Rect(value) posizionano l’annotazione sulla pagina.

Iterare e rimuovere le annotazioni

AnnotationCollection supporta il conteggio, l’accesso indicizzato, i controlli di appartenenza e la rimozione per valore o per indice:

#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) e Remove(annotation) operano su un riferimento di annotazione specifico; Delete(index) rimuove per posizione, e Delete(annotation) rimuove una specifica annotazione senza necessità del suo indice. IsReadOnly() segnala se la collezione può essere modificata.

Lettura delle annotazioni da un documento esistente

Quando un documento viene caricato, le sue annotazioni sono già popolate e possono essere ispezionate senza aggiungere nulla. Annotation.AnnotationType() segnala il sottotipo (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark, e altri):

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

L’ordine delle annotazioni e il sottotipo sono preservati durante un ciclo di salvataggio/riapertura, quindi il codice che indicizza Annotations() dopo il caricamento di un documento vede la stessa sequenza presente quando il file è stato scritto.

Annotazioni di collegamento e azioni

LinkAnnotation collega una regione cliccabile a una pagina e invia un PdfAction quando attivata. NamedAction salta a una destinazione di navigazione predefinita, JavascriptAction esegue una stringa ECMAScript, e SubmitFormAction invia dati di un modulo a un URL tramite un 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) accetta qualsiasi sottotipo PdfAction e lo clona internamente, così l’annotazione conserva la propria copia dell’azione. LinkAnnotation.Destination() / Destination(value) impostano una destinazione di navigazione esplicita invece di un’azione, e Highlighting() / Highlighting(value) controllano il feedback visivo mostrato mentre il collegamento viene cliccato.

Aspetto dell’annotazione: bordo, flag e colore

Ogni Annotation espone un Border, un bitfield di AnnotationFlags, e un Color usato per renderizzare il suo aspetto:

#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() accetta BorderStyle::Solid, Dashed, Beveled, Inset o Underline. Border.Effect() supporta inoltre un contorno BorderEffect::Cloudy con EffectIntensity() che controlla quanto è pronunciato. AnnotationFlags è un bitfield — combina valori come Print, NoZoom, ReadOnly e LockedContents per controllare come un’annotazione si comporta in un visualizzatore senza modificare il suo contenuto visibile.

Appiattimento delle annotazioni

Un’unica annotazione può essere appiattita — unita al contenuto della pagina e resa non interattiva — chiamando direttamente 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");
}

Per operazioni di annotazione su tutto il documento, PdfAnnotationEditor segue il modello condiviso Facade usato in tutto il API: collega un documento sorgente con BindPdf(), applica una o più operazioni di annotazione, quindi scrivi il risultato con 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() rimuove ogni annotazione dal documento associato; DeleteAnnotations(annotType) limita la rimozione a una singola AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) e ImportAnnotationsFromFdf(fdfFile) caricano dati di annotazione esportati da un altro visualizzatore PDF.

Suggerimenti e migliori pratiche

Aggiungi sempre un’annotazione appena costruita a Page.Annotations() prima di chiamare Document.Save() — un’annotazione che non viene mai aggiunta a una collezione non viene scritta nel file di output.
Usa AnnotationCollection.Contains(annotation) prima di chiamare Remove() se non sei certo che l’annotazione sia ancora presente; Remove() restituisce false anziché generare un’eccezione quando l’annotazione è assente.
Controlla Annotation.AnnotationType() prima di eseguire il casting o il branching sul comportamento del sottotipo quando iteri le annotazioni caricate da un file PDF non attendibile o di terze parti.
Appiattisci le annotazioni con Annotation.Flatten() (o PdfAnnotationEditor.FlatteningAnnotations() per l’intero documento) prima di archiviare un documento affinché i revisori su altri strumenti vedano la stessa apparenza che hai creato.
AnnotationFlags è un bitfield — combina i flag con i valori interi sottostanti dell’enumerazione invece di presumere che solo un flag possa essere attivo alla volta.

Problemi comuni

Problema	Causa	Correzione
Annotazione non visibile dopo il salvataggio	L’annotazione è stata costruita ma non è mai stata aggiunta a `Page.Annotations()`	Chiamare `page.Annotations().Add(annotation)` prima di `doc.Save()`
`Remove()` restituisce `false`	Il riferimento all’annotazione fornito non corrisponde a una voce attualmente presente nella collezione	Usa `Contains()` prima, oppure rimuovi per indice con `Delete(index)`
Tipo di annotazione errato dopo il ricaricamento	Il codice ha supposto un sottotipo specifico senza controllare `AnnotationType()`	Esegui un branch su `Annotation.AnnotationType()` prima di trattare l’oggetto come un sottotipo specifico
L’azione del collegamento sembra non impostata dopo l’assegnazione	Una variabile locale `PdfAction` è uscita dallo scope; `LinkAnnotation.Action()` restituisce la copia clonata dell’annotazione, non l’oggetto originale	Leggi nuovamente l’azione tramite `link.Action()` anziché mantenere la variabile locale originale
L’operazione `PdfAnnotationEditor` non ha effetto	`BindPdf()` non è stato chiamato, oppure è stato chiamato con un percorso che non esiste	Verifica che `BindPdf()` abbia successo prima di chiamare `FlatteningAnnotations()` o `DeleteAnnotations()`

FAQ

Come aggiungo un’annotazione in stile commento a una pagina PDF?

Costruisci un TextAnnotation con il target Document, imposta il suo Rect() e Contents(), poi aggiungilo a page.Annotations() prima di salvare.

Come faccio a capire che tipo di annotazione sto guardando?

Chiama Annotation.AnnotationType(), che restituisce un valore enum AnnotationType come Text, Link, Highlight, FreeText, FileAttachment o Watermark.

Un’annotazione può contenere più di un flag?

Sì. AnnotationFlags è un bitfield (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents e altri), quindi più flag possono essere combinati su un’unica annotazione.

Qual è la differenza tra appiattire un’annotazione e appiattire un documento?

Annotation.Flatten() unisce una singola annotazione al contenuto della sua pagina. PdfAnnotationEditor.FlatteningAnnotations() (opzionalmente limitato per intervallo di pagine e AnnotationType tramite la sovraccarico che accetta start, end e annotType) appiattisce l’intero documento collegato in una sola chiamata.

Come rimuovo tutte le annotazioni di un certo tipo da un documento?

Associa il documento con PdfAnnotationEditor.BindPdf(), chiama DeleteAnnotations(annotType) con il AnnotationType di destinazione, quindi Save() il risultato.

API Reference Riepilogo

Classe/Metodo	Descrizione
`Annotation`	Classe base astratta per tutti i sottotipi di annotazione PDF
`Annotation.Rect()` / `Rect(value)`	Ottieni o imposta il rettangolo di delimitazione dell’annotazione
`Annotation.Contents()` / `Contents(value)`	Ottieni o imposta il contenuto di testo dell’annotazione
`Annotation.AnnotationType()`	Restituisce il valore enum `AnnotationType` per questa annotazione
`Annotation.Flags()` / `Flags(value)`	Ottieni o imposta il bitfield `AnnotationFlags`
`Annotation.Border()` / `Border(value)`	Ottieni o imposta il `Border` dell’annotazione
`Annotation.Color()` / `Color(value)`	Ottieni o imposta la visualizzazione dell’annotazione `Color`
`Annotation.Flatten()`	Unisce questa annotazione al contenuto della pagina, rendendola non-interattiva
`AnnotationCollection`	Raccolta ordinata di annotazioni su una pagina, restituita da `Page.Annotations()`
`AnnotationCollection.Add(annotation)` / `Add(annotation, considerRotation)`	Aggiunge un’annotazione alla raccolta
`AnnotationCollection.Count()`	Restituisce il numero di annotazioni nella raccolta
`AnnotationCollection.Contains(annotation)`	Riporta se la raccolta contiene l’annotazione fornita
`AnnotationCollection.Remove(annotation)`	Rimuove un’annotazione specifica; restituisce `false` se non trovata
`AnnotationCollection.Delete(index)` / `Delete(annotation)`	Rimuove un’annotazione per indice o per riferimento
`AnnotationCollection.Clear()`	Rimuove tutte le annotazioni dalla collezione
`TextAnnotation`	Annotazione in stile nota adesiva con `Open()` e `Icon()` (`TextIcon`)
`LinkAnnotation`	Regione cliccabile che invia un `PdfAction` tramite `Action()` / `Action(value)`
`LinkAnnotation.Destination()` / `Destination(value)`	Ottieni o imposta un target di navigazione esplicito
`HighlightAnnotation`	Contrassegna un intervallo di testo con un colore di evidenziazione
`FreeTextAnnotation`	Visualizza un richiamo di testo; configurato tramite `Justification()`, `DefaultAppearanceObject()`, `Callout()`
`CircleAnnotation`	Disegna un’ellisse all’interno del rettangolo dell’annotazione
`WatermarkAnnotation`	Sovrapponi l’annotazione con un `Opacity()` / `Opacity(value)` accessor
`WidgetAnnotation`	Annotazione dell’aspetto del campo modulo con `ReadOnly()`, `Required()`, `Exportable()`, `DefaultAppearance()`
`NamedAction`	Azione di navigazione predefinita (`PredefinedAction` enum) collegabile a un `LinkAnnotation`
`JavascriptAction`	Esegue una stringa ECMAScript tramite `Script()` / `GetECMAScriptString()`
`SubmitFormAction`	Invia i dati del modulo a un URL `FileSpecification` tramite `Url()` / `Url(value)`
`Border`	Bordo dell’annotazione con `Width()`, `Style()` (`BorderStyle`), `Effect()` (`BorderEffect`)
`PdfAnnotationEditor`	Facade per l’importazione, la modifica, l’appiattimento e l’eliminazione delle annotazioni a livello di documento
`PdfAnnotationEditor.FlatteningAnnotations()`	Appiattisce le annotazioni nel documento associato
`PdfAnnotationEditor.DeleteAnnotations(annotType)`	Elimina tutte le annotazioni di un dato `AnnotationType`
`PdfAnnotationEditor.ImportAnnotationsFromXfdf(xfdfFile)`	Importa annotazioni da un file XFDF

Vedi anche

Aspose.PDF — Enterprise Documentation