Anotaciones y Formularios

Anotaciones y Formularios

Aspose.PDF FOSS para .NET le brinda acceso completo de lectura/escritura a anotaciones PDF
y campos interactivos de AcroForm. El punto de entrada principal para anotaciones es
Page.Annotations (un AnnotationCollection), mientras que los campos de formulario se acceden
a través de Document.Form. Ambos subsistemas funcionan completamente en memoria y no requieren
clave de licencia.

Agregar anotaciones

AnnotationCollection expone métodos auxiliares tipados para cada tipo de anotación estándar. Cada método acepta un Rectangle que define la posición de la anotación en la página más los parámetros específicos 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);

Anotaciones de enlace y acciones

Los enlaces combinan un rectángulo clicable con un PdfAction. La biblioteca admite
acciones URI, GoTo, JavaScript, Named y 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");

Para leer un enlace después de abrir un PDF guardado, convierta la anotación a LinkAnnotation y examine su propiedad Uri o resuelva el diccionario de acción mediante PdfAction.Create.

Anotaciones de marcado y formas

Las anotaciones de marcado (resaltar, subrayar, tachar) marcan el texto existente. Las anotaciones de forma (cuadrado, círculo, línea, tinta) dibujan geometría en la página.

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

Anotaciones de sello

Las anotaciones de sello superponen una imagen o un ícono predefinido en una página.

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

Aplanar anotaciones

Llama Flatten() en cualquier anotación para quemar su apariencia visual en el flujo de contenido de la página y eliminarla de la lista de anotaciones interactivas.

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

El patrón Visitor con AnnotationSelector

AnnotationSelector implementa el patrón visitante para que puedas filtrar anotaciones por tipo sin casteo manual.

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
}

Pase una instancia de anotación tipada al constructor para filtrar solo ese tipo:

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

Campos de formulario interactivo

Acceda a los campos AcroForm a través de Document.Form. La clase Form expone operaciones de lectura/escritura a nivel de campo y admite la exportación a JSON.

using var doc = Document.Open(pdfBytes);

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

Las subclases de Field incluyen TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField y SignatureField.

Exportando datos del formulario a JSON

WidgetAnnotation proporciona sobrecargas ExportToJson para serializar datos de campo a un flujo o ruta de archivo. Un parámetro opcional ExportFieldsToJsonOptions controla el formato de salida.

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

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

Consejos y Mejores Prácticas

• Siempre especifique coordenadas explícitas Rectangle en unidades del espacio de usuario PDF (1/72 de pulgada).
• Utilice AddLinkAnnotation con un PdfAction para máxima flexibilidad — se admiten URI, GoTo, JavaScript y acciones con nombre.
• Llame a Flatten() antes de distribuir un PDF si desea que las anotaciones aparezcan en visores no interactivos.
• Acceda a los campos de formulario mediante Document.Form.Fields en lugar de iterar las anotaciones de página — la colección de formularios gestiona la agrupación de campos entre páginas.
• Guarde y vuelva a abrir el documento para verificar la fidelidad del ciclo de ida y vuelta de las anotaciones, especialmente para acciones personalizadas.

Problemas comunes

Preguntas frecuentes

¿Cómo añado un hipervínculo a una página PDF?

Utilice page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) para crear un enlace URI clicable en el rectángulo especificado.

¿Puedo leer los valores de los campos de formulario de un PDF existente?

Sí. Abra el documento con Document.Open, luego itere Document.Form.Fields y lea la propiedad Value en cada Field.

¿Qué tipos de anotación admite la biblioteca?

La biblioteca admite texto, texto libre, enlace, resaltado, subrayado, tachado, cuadrado, círculo, línea, tinta, sello, cursor, archivo adjunto, sonido, polígono, polilínea, widget, marca de agua y anotaciones 3D. Todos los tipos están disponibles a través de AnnotationCollection métodos auxiliares o construcción directa.

¿Cómo filtro las anotaciones por tipo?

Utilice AnnotationSelector con una anotación de plantilla tipada. Llame a page.Accept(selector) e inspeccione selector.Selected para encontrar anotaciones coincidentes.

¿Puedo aplanar solo anotaciones específicas?

Sí. Llame a Flatten() en instancias individuales de Annotation en lugar de iterar toda la colección.

Resumen de referencia de API

Ver también

• Aspose.PDF para .NET Enterprise Product