Come lavorare con le annotazioni in TypeScript

Questa guida mostra come aggiungere, appiattire e cercare le annotazioni PDF con Aspose.PDF FOSS per TypeScript. La classe Page espone un metodo Add* per ogni sottotipo di annotazione — markup (evidenziazione, sottolineatura, barratura, ondulata), forme (quadrato, cerchio, linea, poligono, inchiostro), testo (nota adesiva, testo libero) e collegamenti — ciascuno restituisce un handle tipizzato Annotation che può essere letto nuovamente o appiattito in seguito. Richiede Node.js 22 o versioni successive.

Guida passo passo

Passo 1: Installa il pacchetto

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta che il pacchetto è installato:

import { Document } from '@asposefoss/pdf';

Passo 2: Importa le classi richieste

Importa Document per aprire il file e Page per le firme dei tipi di annotazione utilizzate nei passaggi seguenti:

import { Document, Page } from '@asposefoss/pdf';

Passo 3: Aggiungi annotazioni di markup

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() e Page.AddStrikeOut() accettano tutti un array quads — un quad di 8 numeri (x1,y1,x2,y2,x3,y3,x4,y4) per ogni regione di testo evidenziata — più un color e un contents opzionale. La libreria genera automaticamente lo stream di aspetto (/AP) per tutti e quattro i sottotipi:

import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({
  quads: [72, 700, 300, 700, 72, 685, 300, 685],
  color: [1, 1, 0],
  contents: 'Yellow highlight',
});
page.AddUnderline({
  quads: [72, 660, 300, 660, 72, 645, 300, 645],
  color: [0, 0, 1],
});
page.AddStrikeOut({
  quads: [72, 620, 300, 620, 72, 605, 300, 605],
  color: [1, 0, 0],
});

doc.WriteTo('annotated.pdf');

Passo 4: Aggiungi annotazioni di forma e inchiostro

Page.AddSquare() e Page.AddCircle() accettano un rect di delimitazione più color (tratto) e fill opzionale. Page.AddLine() accetta un line a 4 numeri (x1,y1,x2,y2) e terminazioni a freccia opzionali. Page.AddInk() accetta paths — un array di array piatti di coppie di punti, uno per tratto di penna:

page.AddSquare({ rect: [100, 500, 220, 560], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [250, 500, 370, 560], color: [0, 0.5, 0], width: 2 });
page.AddLine({
  line: [100, 470, 370, 470],
  color: [0, 0, 0.7],
  width: 2,
  startEnding: 'OpenArrow',
  endEnding: 'ClosedArrow',
});
page.AddInk({
  paths: [[100, 400, 130, 430, 160, 390, 190, 420]],
  color: [0.6, 0, 0.6],
  width: 2,
});

Passo 5: Aggiungi una nota adesiva e testo libero

Page.AddTextNote() posiziona un’icona cliccabile che apre un popup di commento. Page.AddFreeText() disegna il testo direttamente sulla pagina all’interno del suo rect:

page.AddTextNote({
  rect: [400, 700, 420, 720],
  icon: 'Note',
  author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [400, 600, 550, 660],
  contents: 'FreeText sample',
  fontSize: 10,
  align: 'center',
  fill: [1, 1, 0.8],
  width: 1,
});

Passo 6: Appiattisci un’annotazione in contenuto statico

Ogni gestore di annotazione restituito da una chiamata Add* dispone di un metodo Flatten() che incorpora l’aspetto dell’annotazione nel flusso di contenuto della pagina e lo rimuove da /Annots. Dopo l’appiattimento non rimane nulla da cliccare o modificare in un visualizzatore:

const note = page.AddFreeText({
  rect: [210, 535, 470, 590],
  contents: 'Sticky note — flattened into the page.',
  fontSize: 11,
  align: 'left',
});

note.Flatten(); // -> boolean; bakes the annotation, unwires itself from /Annots

Passo 7: Cerca testo dell’annotazione

Page.SearchAnnotationText() and Page.SearchAnnotations() sono disgiunti in entrambe le direzioni: SearchAnnotationText() corrisponde ai metadati dell’annotazione letterale (/Contents, /T, /Subj), mentre SearchAnnotations() corrisponde al rendered testo delle annotazioni di markup come FreeText:

const metadataHits = page.SearchAnnotationText('confidential');
for (const hit of metadataHits) {
  console.log(hit.key, hit.value); // e.g. 'Contents', 'confidential'
}

const renderedHits = page.SearchAnnotations('confidential');
console.log(renderedHits.length);

Problemi comuni e soluzioni

Page.AddHighlight() (o un altro metodo di markup) viene disegnato nel posto sbagliato. quads è un array piatto di 8 numeri (x1,y1,x2,y2,x3,y3,x4,y4), non un rect — passare un rettangolo a 4 numeri produce un quad degenerato o mancante. Crea un quad per ogni riga di testo evidenziato.

Un’annotazione appiattita è ancora cliccabile. Flatten() deve essere chiamato sull’oggetto restituito da Add* la chiamata, e il documento deve essere salvato (doc.WriteTo() / doc.Save()) dopo l’appiattimento — la modifica esiste solo in memoria finché il file non viene riscritto.

SearchAnnotationText() non restituisce risultati anche se il testo è visibile nella pagina. Cerca solo nei campi dei metadati delle annotazioni (/Contents, /T, /Subj) — testo di markup visibile renderizzato dall’aspetto stesso dell’annotazione (ad esempio un FreeText body) è trovato da SearchAnnotations() invece, e non ricerca neanche il contenuto ordinario della pagina (usa Page.GetText() or Page.Search() per questo).

I segni di redazione non compaiono quando si cercano le annotazioni. Page.AddRedact() crea un RedactAnnotation, un sottotipo distinto dalle annotazioni markup/shape/text trattate qui — vedi il Redaction guida.

Domande frequenti

Quanti sottotipi di annotazione supporta `Page`?

La libreria genera le apparenze per markup (highlight, underline, strikeout, squiggly), shapes (square, circle, line, polygon, ink), text (sticky note, free text), links e stamps — oltre alle annotazioni di file attachment e redaction, che sono trattate nelle loro guide pratiche.

Posso leggere le annotazioni che esistono già su una pagina?

Sì — Page.Annotations restituisce le annotazioni esistenti come un array di handle tipizzati che puoi ispezionare, modificare o flatten, e Page.RemoveAnnotation(a) ne rimuove una.

Qual è la differenza tra l’appiattimento di un’annotazione e l’applicazione di una redazione?

Flatten() cuoce l’annotazione appearance nella pagina e rimuove l’oggetto annotazione, ma qualsiasi testo o contenuto immagine al di sotto rimane intatto. ApplyRedactions() riscrive distruttivamente il flusso di contenuto in modo che il contenuto coperto stesso scompaia — vedi la guida alla Redazione per i dettagli.

Le annotazioni vengono conservate durante un ciclo di salvataggio/apertura?

Sì — le annotazioni aggiunte prima di doc.WriteTo() / doc.Save() vengono scritte nel PDF e lette nuovamente correttamente al successivo Document.Open() / Document.OpenFile().