Introduzione

Il post introduttivo tratta brevemente le annotazioni: evidenziazioni, sottolineature, note adesive e timbri, aggiunti tramite Page.AddHighlight(), Page.AddUnderline() e metodi simili. Questa è una piccola parte di ciò che un Page supporta realmente — la galleria di annotazioni in questa libreria copre markup, forme a mano libera, collegamenti con navigazione reale e azioni di invio di moduli, e ricerca, tutti raggiungibili direttamente da Page.

Questo post esamina il resto di quella superficie: i metodi di annotazione a forma e a mano libera, cosa può effettivamente fare l’azione di un’annotazione Link, e i due modi diversi per cercare il contenuto dell’annotazione a seconda che il testo che stai cercando sia nell’aspetto dell’annotazione o nel suo commento /Contents.

Ogni metodo di annotazione restituisce un handle tipizzato limitato all’annotazione appena creata, e ogni annotazione su una pagina è leggibile successivamente tramite page.Annotations.

Cosa è incluso

Annotazioni markup

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() e Page.AddStrikeOut() accettano tutti la stessa forma di opzioni — un insieme di quad points che delimitano la regione di testo e un colore opzionale — e tutti e quattro restituiscono un MarkupAnnotation. I quad points sono tipicamente derivati da una ricerca di testo o da un rettangolo di testo noto.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

Note e Testo Autonomo

Page.AddTextNote() aggiunge un’icona classica di nota adesiva che apre un popup di commento al clic, restituendo un TextAnnotation. Page.AddFreeText() invece disegna il suo testo direttamente sulla pagina all’interno di una casella con bordo, con la propria dimensione del carattere, allineamento e colore di riempimento — utile per avvisi che dovrebbero essere visibili senza aprire nulla.

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

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

Forme e Inchiostro a Mano Libera

Page.AddSquare() e Page.AddCircle() disegnano un rettangolo o un’ellisse con bordo, ciascuno con un riempimento interno opzionale. Page.AddLine() traccia una linea retta tra due punti, con stili di estremità freccia selezionabili indipendentemente (startEnding/endEnding, ad es. 'OpenArrow'/'ClosedArrow') a ciascuna estremità. Page.AddPolygon() e Page.AddPolyline() disegnano forme chiuse e aperte a più punti da un elenco piatto di coordinate, e Page.AddInk() registra una o più tratti a mano libera come paths di elenchi di punti.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

Collegamenti e le Loro Azioni

Page.AddLink() restituisce un LinkAnnotation il cui action decide cosa succede al clic: { type: 'uri', uri: '...' } apre un URL esterno, { type: 'goto', page: N } salta a una pagina all’interno dello stesso documento, e { type: 'submit', url: '...', format: 'html' } invia i valori attuali dei campi del modulo a un endpoint. Un numero di pagina goto fuori intervallo o un oggetto azione malformato viene rifiutato al momento della creazione anziché accettato silenziosamente.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

Ricerca del Contenuto delle Annotazioni

Due metodi diversi cercano il testo dell’annotazione, e sono deliberatamente disgiunti: Page.SearchAnnotations() cerca il testo della stessa apparizione di un’annotazione disegna — l’etichetta visibile su un FreeText o timbro, per esempio — mentre Page.SearchAnnotationText() cerca il testo contenuto nell’annotazione /Contents voce, come il corpo del commento di un appunto adesivo. Una corrispondenza in una non implica una corrispondenza nell’altra.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

Le annotazioni non più necessarie possono essere rimosse direttamente con Page.RemoveAnnotation(), passando l’handle dell’annotazione o il suo dizionario sottostante.

Guida rapida

Installa il pacchetto, quindi aggiungi un evidenziatore, un collegamento e una nota adesiva a una pagina esistente:

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
import { Document } from '@asposefoss/pdf';

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

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

Formati supportati

FormatoEstensioneLeggiScrivi
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Open source e licenza

Aspose.PDF FOSS per TypeScript è rilasciato sotto licenza MIT, con il codice sorgente pubblicato su GitHub. Non è presente alcuna filigrana di valutazione, limite di utilizzo o file di licenza separato da gestire, e la libreria può essere usata in prodotti commerciali senza royalty.

Il pacchetto è attualmente alla versione 0.1.0, riflettendo uno sviluppo attivo nelle fasi iniziali. Node.js (>=22) è l’unico requisito di runtime e il pacchetto non ha altre dipendenze di terze parti.

Guida introduttiva

Risorse correlate