Annotations et formulaires

Annotations et formulaires

Aspose.PDF FOSS for .NET vous donne un accès complet en lecture/écriture aux annotations PDF
et aux champs AcroForm interactifs. Le point d’entrée principal pour les annotations est
Page.Annotations (un AnnotationCollection), tandis que les champs de formulaire sont accessibles
via Document.Form. Les deux sous‑systèmes fonctionnent entièrement en mémoire et ne nécessitent aucune
clé de licence.

Ajout d’annotations

AnnotationCollection expose des méthodes d’assistance typées pour chaque type d’annotation standard. Chaque méthode accepte un Rectangle définissant la position de l’annotation sur la page ainsi que des paramètres spécifiques au type.

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

Annotations de lien et actions

Les liens combinent un rectangle cliquable avec un PdfAction. La bibliothèque prend en charge
URI, GoTo, JavaScript, Named et Launch actions.

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

Pour lire à nouveau un lien après l’ouverture d’un PDF enregistré, convertissez l’annotation en LinkAnnotation et inspectez sa propriété Uri ou résolvez le dictionnaire d’action via PdfAction.Create.

Annotations de balisage et de forme

Les annotations de balisage (surlignage, soulignement, barré) marquent le texte existant. Les annotations de forme (carré, cercle, ligne, encre) dessinent la géométrie sur la page.

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

Annotations d’estampille

Les annotations de tampon superposent une image ou une icône prédéfinie sur une page.

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

Aplatir les annotations

Appelez Flatten() sur n’importe quelle annotation pour graver son apparence visuelle dans le flux de contenu de la page et la supprimer de la liste d’annotations interactives.

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

Le patron de visiteur avec AnnotationSelector

AnnotationSelector implémente le pattern visiteur afin que vous puissiez filtrer les annotations par type sans conversion manuelle.

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
}

Passez une instance d’annotation typée au constructeur pour filtrer uniquement ce type :

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

Champs de formulaire interactifs

Accédez aux champs AcroForm via Document.Form. La classe Form expose des opérations de lecture/écriture au niveau du champ et prend en charge l’exportation JSON.

using var doc = Document.Open(pdfBytes);

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

Les sous‑classes de Field incluent TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField et SignatureField.

Exportation des données de formulaire au format JSON

WidgetAnnotation fournit des surcharges ExportToJson pour sérialiser les données de champ vers un flux ou un chemin de fichier. Un paramètre ExportFieldsToJsonOptions facultatif contrôle le formatage de la sortie.

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

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

Conseils et meilleures pratiques

• Spécifiez toujours des coordonnées Rectangle explicites en unités d’espace utilisateur PDF (1/72 pouce).
• Utilisez AddLinkAnnotation avec un PdfAction pour une flexibilité maximale — les actions URI, GoTo, JavaScript et Named sont toutes prises en charge.
• Appelez Flatten() avant de distribuer un PDF si vous souhaitez que les annotations apparaissent dans les visionneuses non interactives.
• Accédez aux champs de formulaire via Document.Form.Fields plutôt qu’en parcourant les annotations de page — la collection de formulaires gère le regroupement des champs sur plusieurs pages.
• Enregistrez et rouvrez le document pour vérifier la fidélité du cycle complet des annotations, en particulier pour les actions personnalisées.

Problèmes courants

FAQ

Comment ajouter un hyperlien à une page PDF ?

Utilisez page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) pour créer un lien URI cliquable à la zone rectangulaire spécifiée.

Puis-je lire les valeurs des champs de formulaire d’un PDF existant ?

Oui. Ouvrez le document avec Document.Open, puis itérez Document.Form.Fields et lisez la propriété Value sur chaque Field.

Quels types d’annotation la bibliothèque prend‑elle en charge ?

La bibliothèque prend en charge le texte, le texte libre, le lien, le surlignage, le soulignement, le barré, le carré, le cercle, la ligne, l’encre, le tampon, le caret, la pièce jointe de fichier, le son, le polygone, la polyligne, le widget, le filigrane et les annotations 3D. Tous les types sont disponibles via les méthodes d’assistance AnnotationCollection ou par construction directe.

Comment filtrer les annotations par type ?

Utilisez AnnotationSelector avec une annotation de modèle typée. Appelez page.Accept(selector) et inspectez selector.Selected pour les annotations correspondantes.

Puis-je aplatir uniquement des annotations spécifiques ?

Oui. Appelez Flatten() sur des instances individuelles de Annotation plutôt que d’itérer sur l’ensemble de la collection.

Résumé de la référence API

Voir aussi

• Aspose.PDF pour .NET Produit Enterprise