Annotazioni e Moduli

Annotazioni e Moduli

Aspose.PDF FOSS per .NET ti offre pieno accesso in lettura/scrittura alle annotazioni PDF
e ai campi AcroForm interattivi. Il punto di ingresso principale per le annotazioni è
Page.Annotations (un AnnotationCollection), mentre i campi modulo sono accessibili
tramite Document.Form. Entrambi i sottosistemi funzionano interamente in memoria e non richiedono
una chiave di licenza.

Aggiunta di annotazioni

AnnotationCollection espone metodi di supporto tipizzati per ogni tipo di annotazione standard. Ogni metodo accetta un Rectangle che definisce la posizione dell’annotazione sulla pagina più i parametri specifici del tipo.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// Text (sticky-note) annotation
page.Annotations.AddTextAnnotation(
    new Rectangle(72, 720, 200, 740),
    contents: "Review this paragraph",
    title: "Editor",
    open: true);

// Highlight annotation
page.Annotations.AddHighlightAnnotation(
    new Rectangle(72, 680, 300, 700),
    quadPoints: null,
    color: new double[] { 1, 1, 0 });

// Free-text annotation (rendered directly on the page)
page.Annotations.AddFreeTextAnnotation(
    new Rectangle(72, 640, 350, 660),
    contents: "Inline note",
    fontName: "Helvetica",
    fontSize: 10,
    color: new double[] { 0, 0, 0 });

using var ms = new MemoryStream();
doc.Save(ms);

Annotazioni e azioni di collegamento

I collegamenti combinano un rettangolo cliccabile con un PdfAction. La libreria supporta URI, GoTo, JavaScript, Named e azioni Launch.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// URI link
var uriAction = PdfAction.CreateUri("https://aspose.com");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 700, 200, 720), uriAction);

// GoTo link (jump to page 3)
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 660, 200, 680),
    destinationPage: 3,
    destRect: new Rectangle(0, 0, 612, 792));

// JavaScript link
var jsAction = PdfAction.CreateJavaScript("app.alert('Hello');");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 620, 200, 640), jsAction);

doc.Save("links.pdf");

Per leggere nuovamente un collegamento dopo aver aperto un PDF salvato, esegui il cast dell’annotazione a LinkAnnotation e ispeziona la sua proprietà Uri o risolvi il dizionario dell’azione tramite PdfAction.Create.

Annotazioni di markup e forme

Annotazioni di markup (evidenziazione, sottolineatura, barrato) contrassegnano il testo esistente. Le annotazioni di forma (quadrato, cerchio, linea, inchiostro) disegnano geometrie sulla pagina.

var page = doc.Pages[1];

// Underline
page.Annotations.AddUnderlineAnnotation(
    new Rectangle(72, 600, 300, 620),
    quadPoints: null,
    color: new double[] { 1, 0, 0 });

// Square
page.Annotations.AddSquareAnnotation(
    new Rectangle(72, 540, 200, 580),
    borderColor: new double[] { 0, 0, 1 },
    fillColor: null,
    lineWidth: 1.5);

// Line
page.Annotations.AddLineAnnotation(
    new Rectangle(72, 500, 300, 520),
    x1: 72, y1: 510, x2: 300, y2: 510,
    color: new double[] { 0, 0.5, 0 },
    lineWidth: 2);

// Ink (freehand)
page.Annotations.AddInkAnnotation(
    new Rectangle(72, 440, 200, 480),
    inkPaths: new[] { new double[] { 80, 450, 120, 470, 160, 450 } },
    color: new double[] { 0.5, 0, 0.5 },
    lineWidth: 1);

Annotazioni timbro

Le annotazioni timbro sovrappongono un’immagine o un’icona predefinita su una pagina.

var stamp = new StampAnnotation(doc);
// Configure stamp properties, then add to page
page.Annotations.Add(stamp);

Appiattimento delle annotazioni

Chiama Flatten() su qualsiasi annotazione per incorporare il suo aspetto visivo nel flusso di contenuto della pagina e rimuoverlo dall’elenco delle annotazioni interattive.

foreach (var annot in doc.Pages[1].Annotations)
{
    annot.Flatten();
}

Il pattern visitor con AnnotationSelector

AnnotationSelector implementa il pattern Visitor in modo da poter filtrare le annotazioni per tipo senza conversioni manuali.

var selector = new AnnotationSelector();
doc.Pages[1].Accept(selector);

// selector.Selected now contains all annotations on page 1
foreach (var annot in selector.Selected)
{
    // Process each annotation by type
}

Passa un’istanza di annotazione tipizzata al costruttore per filtrare solo quel tipo:

var linkFilter = new AnnotationSelector(new LinkAnnotation(page, Rectangle.Empty));
page.Accept(linkFilter);
// linkFilter.Selected contains only LinkAnnotation instances

Campi modulo interattivi

Accedi ai campi AcroForm tramite Document.Form. La classe Form espone operazioni di lettura/scrittura a livello di campo e supporta l’esportazione JSON.

using var doc = Document.Open(pdfBytes);

// Enumerate all fields
foreach (var field in doc.Form.Fields)
{
    Console.WriteLine($"{field.FullName}: {field.Value}");
}

Le sottoclassi di Field includono TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField e SignatureField.

Esportazione dei dati del modulo in JSON

WidgetAnnotation fornisce overload ExportToJson per la serializzazione dei dati di campo in uno stream o percorso file. Un parametro opzionale ExportFieldsToJsonOptions controlla la formattazione dell’output.

using var doc = Document.Open(pdfBytes);
var widget = (WidgetAnnotation)doc.Pages[1].Annotations[1];

using var jsonStream = new MemoryStream();
widget.ExportToJson(jsonStream);

Suggerimenti e migliori pratiche

• Specifica sempre coordinate Rectangle esplicite nelle unità di spazio utente PDF (1/72 di pollice).
• Utilizza AddLinkAnnotation con un PdfAction per la massima flessibilità — sono supportati URI, GoTo, JavaScript e azioni Named.
• Chiama Flatten() prima di distribuire un PDF se desideri che le annotazioni compaiano nei visualizzatori non interattivi.
• Accedi ai campi modulo tramite Document.Form.Fields anziché iterare le annotazioni della pagina — la collezione dei moduli gestisce il raggruppamento dei campi tra pagine.
• Salva e riapri il documento per verificare la fedeltà del round‑trip delle annotazioni, soprattutto per le azioni personalizzate.

Problemi comuni

FAQ

Come aggiungere un collegamento ipertestuale a una pagina PDF?

Usa page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) per creare un collegamento URI cliccabile nel rettangolo specificato.

Posso leggere i valori dei campi modulo da un PDF esistente?

Sì. Apri il documento con Document.Open, quindi itera Document.Form.Fields e leggi la proprietà Value su ogni Field.

Quali tipi di annotazione supporta la libreria?

La libreria supporta testo, testo libero, collegamento, evidenziazione, sottolineatura, barrato, quadrato, cerchio, linea, inchiostro, timbro, cursore, allegato file, suono, poligono, polilinea, widget, filigrana e annotazioni 3D. Tutti i tipi sono disponibili tramite i metodi di supporto AnnotationCollection o mediante costruzione diretta.

Come filtro le annotazioni per tipo?

Usa AnnotationSelector con un’annotazione di modello tipizzato. Chiama page.Accept(selector) e ispeziona selector.Selected per le annotazioni corrispondenti.

Posso appiattire solo annotazioni specifiche?

Sì. Chiama Flatten() su singole istanze Annotation anziché iterare l’intera collezione.

Riepilogo del Riferimento API

Vedi anche

• Aspose.PDF per .NET Enterprise Product