Annotaties en formulieren

Annotaties en formulieren

Aspose.PDF FOSS voor .NET geeft u volledige lees-/schrijftoegang tot PDF-annotaties
en interactieve AcroForm-velden. Het primaire toegangspunt voor annotaties is
Page.Annotations (een AnnotationCollection), terwijl formulier-velden worden benaderd
via Document.Form. Beide subsystemen werken volledig in-memory en vereisen geen
licentiesleutel.

Annotaties toevoegen

AnnotationCollection biedt getypeerde hulpmethoden voor elk standaard annotatietype. Elke methode accepteert een Rectangle die de annotatiepositie op de pagina definieert, plus type‑specifieke parameters.

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

Linkannotaties en acties

Links combineren een klikbare rechthoek met een PdfAction. De bibliotheek ondersteunt URI, GoTo, JavaScript, Named, en Launch‑acties.

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

Om een link terug te lezen nadat een opgeslagen PDF is geopend, cast de annotatie naar LinkAnnotation en inspecteer de Uri‑eigenschap of los het actiedictionary op via PdfAction.Create.

Markeringen en vormannotaties

Markup‑annotaties (markering, onderstrepen, doorhalen) markeren bestaande tekst. Vorm‑annotaties (vierkant, cirkel, lijn, inkt) tekenen geometrie op de 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);

Stempelannotaties

Stempelannotaties leggen een afbeelding of vooraf gedefinieerd pictogram over een pagina.

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

Annotaties flattenen

Roep Flatten() aan op elke annotatie om de visuele weergave ervan in de paginacontentstroom in te branden en deze uit de interactieve annotatielijst te verwijderen.

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

Het visitor‑patroon met AnnotationSelector

AnnotationSelector implementeert het visitor‑patroon zodat je annotaties kunt filteren op type zonder handmatig casten.

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
}

Geef een getypeerde annotatie‑instantie door aan de constructor om alleen op dat type te filteren:

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

Interactieve formuliervelden

Toegang tot AcroForm-velden via Document.Form. De Form-klasse biedt veldniveau lees-/schrijfbewerkingen en ondersteunt JSON-export.

using var doc = Document.Open(pdfBytes);

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

Field-subklassen omvatten TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField en SignatureField.

Formuliergegevens exporteren naar JSON

WidgetAnnotation biedt ExportToJson overloads voor het serialiseren van veldgegevens naar een stream of bestandspad. Een optionele ExportFieldsToJsonOptions-parameter regelt de opmaak van de uitvoer.

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

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

Tips en Best Practices

• Specificeer altijd expliciete Rectangle coördinaten in PDF user-space eenheden (1/72 inch).
• Gebruik AddLinkAnnotation met een PdfAction voor maximale flexibiliteit — URI, GoTo, JavaScript en Named actions worden allemaal ondersteund.
• Roep Flatten() aan voordat u een PDF distribueert als u wilt dat annotaties verschijnen in niet‑interactieve viewers.
• Toegang tot formuliervelden via Document.Form.Fields in plaats van pagina‑annotaties te itereren — de form‑collectie behandelt groepering van velden over pagina’s heen.
• Sla het document op en open het opnieuw om de round‑trip getrouwheid van annotaties te verifiëren, vooral voor aangepaste acties.

Veelvoorkomende problemen

FAQ

Hoe voeg ik een hyperlink toe aan een PDF-pagina?

Gebruik page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) om een klikbare URI‑link te maken op het opgegeven rechthoek.

Kan ik formulier-veldwaarden lezen uit een bestaande PDF?

Ja. Open het document met Document.Open, vervolgens itereren Document.Form.Fields en lees de Value eigenschap op elk Field.

Welke annotatietypen ondersteunt de bibliotheek?

De bibliotheek ondersteunt tekst, vrije tekst, link, markering, onderstrepen, doorhalen, vierkant, cirkel, lijn, inkt, stempel, cursor, bestandsbijlage, geluid, veelhoek, polylijn, widget, watermerk en 3D‑annotaties. Alle typen zijn beschikbaar via AnnotationCollection helper‑methoden of directe constructie.

Hoe filter ik annotaties op type?

Gebruik AnnotationSelector met een getypeerde sjabloonannotatie. Roep page.Accept(selector) aan en inspecteer selector.Selected voor overeenkomende annotaties.

Kan ik alleen specifieke annotaties flatten?

Ja. Roep Flatten() aan op individuele Annotation-instanties in plaats van de hele collectie te itereren.

API-referentieoverzicht

Zie ook

• Aspose.PDF for .NET Enterprise Product