Annotations

Anotações

Esta página cobre a criação, leitura, pesquisa e achatamento de anotações PDF. Page expõe um método Add*() por subtipo de anotação, cada um retornando um manipulador Annotation ao vivo; a classe base Annotation e seus subtipos (TextAnnotation, StampAnnotation, MarkupAnnotation e outros) expõem as propriedades da anotação para leitura e edição.


Criando Anotações de Marcação, Nota e Link

Os quatro métodos de marcação de texto — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() e Page.AddStrikeOut() — recebem um array quads (/QuadPoints) e retornam um MarkupAnnotation. Page.AddLink() cria uma região clicável com um URI ou ação interna, e Page.AddTextNote() adiciona um ícone de nota adesiva que abre um pop-up com texto contents, retornando um TextAnnotation.

page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });

page.AddLink({
  rect: [100, 700, 220, 716],
  action: { type: 'uri', uri: 'https://example.com' },
  border: 0,
});

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

Page também expõe métodos de forma e à mão livre — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() e AddStamp() — cada um retornando o manipulador de anotação correspondente para esse subtipo, gerando sua aparência /AP automaticamente.


Lendo e Listando Anotações

page.Annotations é um array de todas as Annotation na página. Cada anotação, independentemente do subtipo, expõe Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden e Opacity; os subtipos adicionam seus próprios campos, como StampAnnotation.StampName ou MarkupAnnotation.QuadPoints.

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

Pesquisando Texto da Anotação

Page.SearchAnnotationText() and Page.SearchAnnotations() são deliberadamente desconexas. SearchAnnotationText() encontra correspondências no texto e uma anotação carries em vez de desenhar — de uma nota’s /Contents, seu autor (/T), ou seu assunto (/Subj) — e retorna AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() encontra correspondências no texto e uma anotação draws, como um FreeText’s palavras visíveis, e retorna AnnotationMatch[] ({ annot, text, quads }).

// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'

// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');

Aplainando Anotações

Annotation.Flatten() incorpora a aparência /AP de uma anotação diretamente no fluxo de conteúdo da página em seu /Rect, então a remove de /Annots. O resultado é conteúdo permanente e estático — não é mais uma anotação distinta que o visualizador pode clicar, editar ou ocultar.

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

Dicas e Melhores Práticas

  • Chame Flatten() no objeto retornado diretamente pela chamada Add*() — uma anotação obtida ao reler page.Annotations posteriormente é uma referência de objeto diferente.
  • SearchAnnotationText() e SearchAnnotations() cobrem textos diferentes: execute ambos se precisar encontrar uma frase independentemente de ter sido digitada em uma nota ou desenhada na página.
  • Os quatro métodos de marcação (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut) geram sua aparência /AP automaticamente — não é necessário desenhar manualmente no fluxo de conteúdo.
  • A criptografia sobrevive a uma ida e volta: anotações adicionadas antes de Document.Save() com uma opção encrypt permanecem válidas após o documento ser reaberto e descriptografado.

Problemas comuns

ProblemaCausaCorreção
page.Annotations.find() retorna undefined para uma anotação que você acabou de adicionarProcurando em um array obsoleto capturado antes da anotação ser adicionadaReleia page.Annotations após a chamada Add*(), ou use o identificador que a chamada retornou diretamente
SearchAnnotationText() não encontra nada para texto visível na páginaO texto é desenhado pela anotação (por exemplo, o corpo de um FreeText), não carregado em /ContentsUse SearchAnnotations() em vez disso — ele corresponde ao texto desenhado
A anotação ainda aparece editável após Flatten()Flatten() foi chamado em uma cópia em vez do manipulador que Add*() retornouChame Flatten() no objeto retornado diretamente pelo método de criação

FAQ

Qual é a diferença entre SearchAnnotationText e SearchAnnotations?

SearchAnnotationText() corresponde ao texto de uma anotação carries — /Contents, /T (autor), ou /Subj — como o corpo de uma nota adesiva. SearchAnnotations() corresponde ao texto de uma anotação draws na página, como um FreeTextpalavras visíveis de ’s. As duas são disjuntas: uma correspondência em uma não aparecerá na outra.

Como faço para tornar uma anotação permanente e não interativa?

Chame Flatten() no manipulador Annotation retornado pelo método Add*() que a criou. Isso incorpora sua aparência ao fluxo de conteúdo da página e a remove de /Annots.

Quais subtipos de anotação são suportados?

Page expõe métodos de criação para marcação de texto (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), notas e balões de chamada (AddTextNote, AddFreeText, AddCaret), links (AddLink), formas (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), tinta à mão livre (AddInk), carimbos (AddStamp) e anexos de arquivo (AddFileAttachment).

Como listar todas as anotações já presentes em uma página?

Leia page.Annotations, um array de manipuladores Annotation. Cada um expõe Subtype, Rect, Color, Contents e as demais propriedades compartilhadas, para que você possa filtrá-los ou inspecioná-los com os métodos padrão de array.


API Reference Resumo

Classe/MétodoDescrição
AnnotationManipulador base sobre qualquer anotação; expõe Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity
Annotation.Flatten()Incorpore a aparência da anotação ao conteúdo estático da página
TextAnnotationUm manipulador de sticky-note /Text; adiciona Icon, Open, Author
StampAnnotationUm /Stamp alça de carimbo de borracha; adiciona StampName
MarkupAnnotationUm manipulador de marcação de texto (Highlight/Underline/StrikeOut/Squiggly); adiciona MarkupType, QuadPoints
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly()Crie uma anotação de marcação de texto sobre /QuadPoints
Page.AddTextNote()Crie uma anotação de nota adesiva
Page.AddLink()Crie um link clicável com um URI ou ação interna
Page.AnnotationsCada Annotation na página, como um array
Page.SearchAnnotationText()Encontre o texto que uma anotação carrega (/Contents, /T, /Subj)
Page.SearchAnnotations()Encontre o texto que uma anotação desenha na página

Ver também

 Português