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 chamadaAdd*()— uma anotação obtida ao relerpage.Annotationsposteriormente é uma referência de objeto diferente. SearchAnnotationText()eSearchAnnotations()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/APautomaticamente — 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çãoencryptpermanecem válidas após o documento ser reaberto e descriptografado.
Problemas comuns
| Problema | Causa | Correção |
|---|---|---|
page.Annotations.find() retorna undefined para uma anotação que você acabou de adicionar | Procurando em um array obsoleto capturado antes da anotação ser adicionada | Releia 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ágina | O texto é desenhado pela anotação (por exemplo, o corpo de um FreeText), não carregado em /Contents | Use 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*() retornou | Chame 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étodo | Descrição |
|---|---|
Annotation | Manipulador 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 |
TextAnnotation | Um manipulador de sticky-note /Text; adiciona Icon, Open, Author |
StampAnnotation | Um /Stamp alça de carimbo de borracha; adiciona StampName |
MarkupAnnotation | Um 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.Annotations | Cada 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 |