Annotations
Annotazioni
Questa pagina copre la creazione, lettura, ricerca e appiattimento delle annotazioni PDF. Page espone un metodo Add*() per ogni sottotipo di annotazione, ciascuno restituisce un handle Annotation live; la classe base Annotation e i suoi sottotipi (TextAnnotation, StampAnnotation, MarkupAnnotation e altri) espongono le proprietà dell’annotazione per la lettura e la modifica.
Creazione di annotazioni Markup, Note e Link
I quattro metodi di markup del testo — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() e Page.AddStrikeOut() — accettano un array quads (/QuadPoints) e restituiscono un MarkupAnnotation. Page.AddLink() crea una regione cliccabile con un URI o un’azione interna, e Page.AddTextNote() aggiunge un’icona di nota adesiva che apre un popup con testo contents, restituendo un 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 espone anche metodi per forme e libera mano — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() e AddStamp() — ognuno restituisce l’handle di annotazione corrispondente a quel sottotipo, generando automaticamente il suo aspetto /AP.
Lettura e elencazione delle annotazioni
page.Annotazioni è un array di tutti i Annotation nella pagina. Ogni annotazione, indipendentemente dal sottotipo, espone Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden e Opacity; i sottotipi aggiungono i propri campi, come StampAnnotation.StampName o MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Ricerca del testo dell’annotazione
Page.SearchAnnotationText() and Page.SearchAnnotations() sono deliberatamente disgiunti. SearchAnnotationText() trova corrispondenze nel testo un’annotazione carries piuttosto che disegna — di una nota’s /Contents, il suo autore (/T), o il suo soggetto (/Subj) — e restituisce AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() trova corrispondenze nel testo un’annotazione draws, come un FreeText’s parole visibili e restituisce 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');Appiattimento delle annotazioni
Annotation.Flatten() incorpora l’aspetto /AP di un’annotazione direttamente nel flusso di contenuto della pagina al suo /Rect, poi lo rimuove da /Annots. Il risultato è un contenuto permanente e statico — non più un’annotazione distinta su cui lo spettatore può fare clic, modificare o nascondere.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();Suggerimenti e migliori pratiche
- Chiama
Flatten()sull’oggetto restituito direttamente dalla chiamataAdd*()— un’annotazione ottenuta rileggendopage.Annotazioniin seguito è un riferimento a un oggetto diverso. SearchAnnotationText()eSearchAnnotations()coprono testo diverso: esegui entrambi se devi trovare una frase indipendentemente dal fatto che sia stata digitata in una nota o disegnata sulla pagina.- I quattro metodi di markup (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) generano automaticamente il loro aspetto/AP— non è necessario disegnare manualmente nel flusso di contenuto. - La crittografia sopravvive a un viaggio di andata e ritorno: le annotazioni aggiunte prima di
Document.Save()con un’opzioneencryptrimangono valide dopo che il documento viene riaperto e decriptato.
Problemi comuni
| Problema | Causa | Correzione |
|---|---|---|
page.Annotations.find() restituisce undefined per un’annotazione appena aggiunta | Ricerca di un array obsoleto catturato prima che l’annotazione fosse aggiunta | Rileggi page.Annotations dopo la chiamata Add*(), oppure usa direttamente l’handle restituito dalla chiamata |
SearchAnnotationText() non trova nulla per il testo visibile sulla pagina | Il testo è generato dall’annotazione (ad es. il corpo di un FreeText), non contenuto in /Contents | Usa SearchAnnotations() invece — corrisponde al testo generato |
L’annotazione appare ancora modificabile dopo Flatten() | Flatten() è stato chiamato su una copia anziché sull’handle restituito da Add*() | Chiama Flatten() sull’oggetto restituito direttamente dal metodo di creazione |
FAQ
Qual è la differenza tra SearchAnnotationText e SearchAnnotations?
SearchAnnotationText() corrisponde al testo di un’annotazione carries — /Contents, /T (autore), o /Subj — ad esempio il corpo di una nota adesiva. SearchAnnotations() corrisponde al testo di un’annotazione draws sulla pagina, ad esempio un FreeText’s parole visibili. I due sono disgiunti: una corrispondenza in uno non apparirà nell’altro.
Come posso rendere un’annotazione permanente e non interattiva?
Chiama Flatten() sul handle Annotation restituito dal metodo Add*() che l’ha creata. Questo incorpora la sua apparizione nello stream di contenuto della pagina e la rimuove da /Annots.
Quali sottotipi di annotazione sono supportati?
Page espone i metodi di creazione per la marcatura del testo (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), note e callout (AddTextNote, AddFreeText, AddCaret), collegamenti (AddLink), forme (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), inchiostro a mano libera (AddInk), timbri (AddStamp) e allegati di file (AddFileAttachment).
Come faccio a elencare ogni annotazione già presente in una pagina?
Leggi page.Annotazioni, un array di handle Annotation. Ognuno espone Subtype, Rect, Color, Contents e le altre proprietà condivise, così puoi filtrare o ispezionarli con i metodi standard degli array.
API Reference Riepilogo
| Classe/Metodo | Descrizione |
|---|---|
Annotation | Gestore di base su qualsiasi annotazione; espone Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | Incorpora l’aspetto dell’annotazione nel contenuto della pagina statica |
TextAnnotation | Una maniglia /Text sticky-note; aggiunge Icon, Open, Author |
StampAnnotation | Una maniglia /Stamp rubber-stamp; aggiunge StampName |
MarkupAnnotation | Una maniglia di markup testuale (Highlight/Underline/StrikeOut/Squiggly); aggiunge MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | Crea un’annotazione di markup testuale su /QuadPoints |
Page.AddTextNote() | Crea un’annotazione sticky-note |
Page.AddLink() | Crea un collegamento cliccabile con un URI o un’azione interna |
Page.Annotations | Ogni Annotation nella pagina, come un array |
Page.SearchAnnotationText() | Trova il testo che un’annotazione contiene (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Trova il testo che un’annotazione disegna sulla pagina |