Adnotări și Formulare

Anotări și Formulare

Aspose.PDF FOSS pentru .NET vă oferă acces complet de citire/scriere la adnotările PDF
și la câmpurile interactive AcroForm. Punctul principal de intrare pentru adnotări este
Page.Annotations (un AnnotationCollection), în timp ce câmpurile de formular sunt accesate
prin Document.Form. Ambele subsisteme funcționează complet în memorie și nu necesită
cheie de licență.

Adăugarea de adnotări

AnnotationCollection expune metode ajutătoare tipizate pentru fiecare tip standard de adnotare. Fiecare metodă acceptă un Rectangle care definește poziția adnotării pe pagină plus parametri specifici tipului.

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

Anotări de link și acțiuni

Legăturile combină un dreptunghi clicabil cu un PdfAction. Biblioteca acceptă acțiunile URI, GoTo, JavaScript, Named și 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");

Pentru a citi din nou un link după deschiderea unui PDF salvat, convertiți adnotarea la LinkAnnotation și inspectați proprietatea Uri sau rezolvați dicționarul de acțiune prin PdfAction.Create.

Adnotări de marcaj și forme

Adnotările de marcare (evidențiere, subliniere, tăiere) marchează textul existent. Adnotările de formă (pătrat, cerc, linie, cerneală) desenează geometrie pe pagină.

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

Adnotări de ștampilă

Adnotările de tip ștampilă suprapun o imagine sau o pictogramă predefinită pe o pagină.

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

Aplatizarea adnotărilor

Apelă Flatten() pe orice adnotare pentru a grava aspectul său vizual în fluxul de conținut al paginii și pentru a o elimina din lista de adnotări interactive.

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

Modelul vizitatorului cu AnnotationSelector

AnnotationSelector implementează modelul vizitator pentru a putea filtra adnotările după tip fără a face conversii manuale.

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
}

Transmite o instanță de adnotare tipizată constructorului pentru a filtra doar pentru acel tip:

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

Câmpuri de formular interactive

Accesați câmpurile AcroForm prin Document.Form. Clasa Form expune operații de citire/scriere la nivel de câmp și suportă exportul JSON.

using var doc = Document.Open(pdfBytes);

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

Subclasele de câmp includ TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField și SignatureField.

Exportarea datelor din formular în JSON

WidgetAnnotation oferă suprasarcini ExportToJson pentru serializarea datelor de câmp într-un flux sau la o cale de fișier. Un parametru opțional ExportFieldsToJsonOptions controlează formatarea ieșirii.

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

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

Sfaturi și cele mai bune practici

• Specificați întotdeauna coordonate explicite Rectangle în unități de spațiu utilizator PDF (1/72 inch).
• Utilizați AddLinkAnnotation cu un PdfAction pentru flexibilitate maximă — URI, GoTo, JavaScript și acțiuni Named sunt toate suportate.
• Apelați Flatten() înainte de a distribui un PDF dacă doriți ca adnotările să apară în vizualizatoare non-interactive.
• Accesați câmpurile de formular prin Document.Form.Fields în loc să iterați adnotările paginii — colecția de formulare gestionează gruparea câmpurilor pe mai multe pagini.
• Salvați și redeschideți documentul pentru a verifica fidelitatea round‑trip a adnotărilor, în special pentru acțiuni personalizate.

Probleme comune

Întrebări frecvente

Cum adaug un hyperlink la o pagină PDF?

Utilizați page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) pentru a crea un link URI clicabil la dreptunghiul specificat.

Pot să citesc valorile câmpurilor de formular dintr-un PDF existent?

Da. Deschide documentul cu Document.Open, apoi iterează Document.Form.Fields și citește proprietatea Value pentru fiecare Field.

Ce tipuri de adnotări suportă biblioteca?

Biblioteca suportă text, text liber, link, evidențiere, subliniere, tăiere, pătrat, cerc, linie, cerneală, ștampilă, cursor, atașament de fișier, sunet, poligon, polilinie, widget, filigran și adnotări 3D. Toate tipurile sunt disponibile prin AnnotationCollection metode auxiliare sau construcție directă.

Cum pot filtra adnotările după tip?

Utilizați AnnotationSelector cu o adnotare de șablon tipizată. Apelați page.Accept(selector) și inspectați selector.Selected pentru adnotări corespunzătoare.

Pot să aplatizez doar adnotările specifice?

Da. Apelați Flatten() pe instanțe individuale ale Annotation în loc să iterați întreaga colecție.

Sumar referință API

Vezi și

• Aspose.PDF for .NET Produs Enterprise