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 chiamata Add*() — un’annotazione ottenuta rileggendo page.Annotazioni in seguito è un riferimento a un oggetto diverso.
  • SearchAnnotationText() e SearchAnnotations() 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’opzione encrypt rimangono valide dopo che il documento viene riaperto e decriptato.

Problemi comuni

ProblemaCausaCorrezione
page.Annotations.find() restituisce undefined per un’annotazione appena aggiuntaRicerca di un array obsoleto catturato prima che l’annotazione fosse aggiuntaRileggi page.Annotations dopo la chiamata Add*(), oppure usa direttamente l’handle restituito dalla chiamata
SearchAnnotationText() non trova nulla per il testo visibile sulla paginaIl testo è generato dall’annotazione (ad es. il corpo di un FreeText), non contenuto in /ContentsUsa 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/MetodoDescrizione
AnnotationGestore 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
TextAnnotationUna maniglia /Text sticky-note; aggiunge Icon, Open, Author
StampAnnotationUna maniglia /Stamp rubber-stamp; aggiunge StampName
MarkupAnnotationUna 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.AnnotationsOgni 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

Vedi anche

 Italiano