Cum să lucrați cu adnotările în TypeScript

Acest ghid arată cum să adaugi, să aplatizezi și să cauți adnotări PDF cu Aspose.PDF FOSS pentru TypeScript. Clasa Page expune o metodă Add* pentru fiecare subtip de adnotare — markup (evidențiere, subliniere, tăiere, ondulat), forme (pătrat, cerc, linie, poligon, cerneală), text (notă adezivă, text liber) și linkuri — fiecare returnând un handle tipizat Annotation care poate fi citit înapoi sau aplatizat ulterior. Necesită Node.js 22 sau o versiune ulterioară.

Ghid pas cu pas

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';

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

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');

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,
});

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,
});

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

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);

Probleme comune și soluții

Page.AddHighlight() (sau altă metodă de marcare) se desenează în locul greșit. quads este un tablou plat cu 8 numere (x1,y1,x2,y2,x3,y3,x4,y4), nu un rect — transmiterea unui dreptunghi cu 4 numere produce un quad degenerat sau lipsă. Construiește un quad pentru fiecare linie de text evidențiat.

O adnotare aplatizată este în continuare clicabilă. Flatten() trebuie să fie apelată pe obiectul returnat de Add* apel, și documentul trebuie salvat (doc.WriteTo() / doc.Save()) după aplatizare — modificarea există doar în memorie până când fișierul este scris înapoi.

SearchAnnotationText() nu returnează rezultate chiar dacă textul este vizibil pe pagină. Caută doar câmpurile de metadate ale adnotărilor (/Contents, /T, /Subj) — textul de marcare vizibil redat din aspectul propriu al adnotării (de ex. un FreeText body) este găsit de SearchAnnotations() în schimb, și nici nu caută conținutul obișnuit al paginii (utilizați Page.GetText() or Page.Search() pentru asta).

Marcajele de redactare nu apar când se caută adnotări. Page.AddRedact() creează un RedactAnnotation, un subtip distinct de adnotările markup/shape/text acoperite aici — consultați Redaction ghidul.

Întrebări frecvente

Câte subtipuri de adnotări suportă Page?

Biblioteca generează apariții pentru markup (evidențiere, subliniere, tăiere, ondulat), forme (pătrat, cerc, linie, poligon, cerneală), text (notă adezivă, text liber), legături și timbre — plus adnotări de atașament de fișier și redacție, care sunt acoperite în propriile ghiduri practice.

Pot citi adnotările care există deja pe o pagină?

Da — Page.Annotations returnează adnotările existente ca un tablou de handle-uri tipizate pe care le poți inspecta, edita sau aplatiza, iar Page.RemoveAnnotation(a) elimină una.

Care este diferența dintre aplatizarea unei adnotări și aplicarea unei redacții?

Flatten() procesează o adnotare appearance în pagină și elimină obiectul de adnotare, dar orice conținut text sau imagine aflat dedesubt rămâne neatins. ApplyRedactions() rescrie în mod distructiv fluxul de conținut, astfel încât conținutul acoperit să dispară — consultați ghidul de Redactare pentru detalii.

Sunt adnotările păstrate pe parcursul unui ciclu de salvare/deschidere?

Da — adnotările adăugate înainte de doc.WriteTo() / doc.Save() sunt scrise în PDF și citite corect la următorul Document.Open() / Document.OpenFile().

Vezi și:

• Nucleu API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base