Anotações e Formulários

Anotações e Formulários

Aspose.PDF FOSS for .NET oferece acesso total de leitura/gravação às anotações PDF e aos campos interativos do AcroForm. O ponto de entrada principal para anotações é Page.Annotations (um AnnotationCollection), enquanto os campos de formulário são acessados através de Document.Form. Ambos os subsistemas funcionam totalmente em memória e não requer chave de licença.

Adicionando anotações

AnnotationCollection expõe métodos auxiliares tipados para cada tipo padrão de anotação. Cada método aceita um Rectangle definindo a posição da anotação na página, além de parâmetros específicos do 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);

Anotações de link e ações

Links combinam um retângulo clicável com um PdfAction. A biblioteca suporta ações URI, GoTo, JavaScript, Named e 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 ler um link de volta após abrir um PDF salvo, faça o cast da anotação para LinkAnnotation e inspecione sua propriedade Uri ou resolva o dicionário de ação via PdfAction.Create.

Anotações de marcação e forma

Anotações de marcação (realce, sublinhado, tachado) marcam o texto existente. Anotações de forma (quadrado, círculo, linha, tinta) desenham geometria na 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);

Anotações de carimbo

Anotações de carimbo sobrepõem uma imagem ou ícone predefinido em uma página.

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

Aplanar anotações

Chame Flatten() em qualquer anotação para gravar sua aparência visual no fluxo de conteúdo da página e removê‑la da lista de anotações interativas.

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

O padrão Visitor com AnnotationSelector

AnnotationSelector implementa o padrão visitor para que você possa filtrar anotações por tipo sem conversão 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
}

Passe uma instância de anotação tipada ao construtor para filtrar apenas esse tipo:

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

Campos de formulário interativos

Acesse os campos AcroForm através de Document.Form. A classe Form expõe operações de leitura/gravação em nível de campo e suporta exportação JSON.

using var doc = Document.Open(pdfBytes);

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

As subclasses de Field incluem TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField e SignatureField.

Exportando dados de formulário para JSON

WidgetAnnotation fornece sobrecargas ExportToJson para serializar dados de campo em um fluxo ou caminho de arquivo. Um parâmetro opcional ExportFieldsToJsonOptions controla a formatação da saída.

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

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

Dicas e Melhores Práticas

• Sempre especifique coordenadas explícitas Rectangle nas unidades de espaço do usuário do PDF (1/72 polegada).
• Use AddLinkAnnotation com um PdfAction para máxima flexibilidade — URI, GoTo, JavaScript e ações Named são todos suportados.
• Chame Flatten() antes de distribuir um PDF se desejar que as anotações apareçam em visualizadores não interativos.
• Acesse os campos de formulário via Document.Form.Fields em vez de iterar as anotações da página — a coleção de formulários lida com o agrupamento de campos entre páginas.
• Salve e reabra o documento para verificar a fidelidade de ida e volta das anotações, especialmente para ações personalizadas.

Problemas Comuns

Perguntas Frequentes

Como adiciono um hyperlink a uma página PDF?

Use page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) para criar um link URI clicável no retângulo especificado.

Posso ler os valores dos campos de formulário de um PDF existente?

Sim. Abra o documento com Document.Open, então itere Document.Form.Fields e leia a propriedade Value em cada Field.

Quais tipos de anotação a biblioteca suporta?

A biblioteca suporta texto, texto livre, link, realce, sublinhado, tachado, quadrado, círculo, linha, tinta, selo, cursor, anexo de arquivo, som, polígono, polilinha, widget, marca d’água e anotações 3D. Todos os tipos estão disponíveis através AnnotationCollection métodos auxiliares ou construção direta.

Como filtro anotações por tipo?

Use AnnotationSelector com uma anotação de modelo tipada. Chame page.Accept(selector) e inspecione selector.Selected para anotações correspondentes.

Posso achatar apenas anotações específicas?

Sim. Chame Flatten() em instâncias individuais de Annotation em vez de iterar toda a coleção.

Resumo da Referência da API

Veja Também

• Aspose.PDF for .NET Produto Enterprise