Annotations

Anotări

Această pagină acoperă crearea, citirea, căutarea și aplatizarea adnotărilor PDF. Page expune o metodă Add*() pentru fiecare subtip de adnotare, fiecare returnând un handle Annotation live; clasa de bază Annotation și subtipurile sale (TextAnnotation, StampAnnotation, MarkupAnnotation și altele) expun proprietățile adnotării pentru citire și editare.


Crearea adnotărilor de tip markup, notă și link

Cele patru metode de markup text — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() și Page.AddStrikeOut() — primesc un tablou quads (/QuadPoints) și returnează un MarkupAnnotation. Page.AddLink() creează o zonă clicabilă cu un URI sau o acțiune internă, iar Page.AddTextNote() adaugă o pictogramă de notă adezivă care deschide un popup cu text contents, returnând 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 expune, de asemenea, metode de formă și de mână liberă — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() și AddStamp() — fiecare returnând handle-ul de adnotare corespunzător pentru acel subtip, generând automat aspectul său /AP.


Citirea și listarea adnotărilor

page.Annotations este un tablou cu fiecare Annotation de pe pagină. Fiecare adnotare, indiferent de subtip, expune Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden și Opacity; subtipurile adaugă propriile câmpuri, cum ar fi StampAnnotation.StampName sau MarkupAnnotation.QuadPoints.

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

Căutarea textului adnotărilor

Page.SearchAnnotationText() and Page.SearchAnnotations() sunt deliberat disjuncte. SearchAnnotationText() găsește potriviri în text o adnotare carries mai degrabă decât să traseze — al unei note /Contents, autorul său (/T), sau subiectul său (/Subj) — și returnează AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() găsește potriviri în text o adnotare draws, cum ar fi un FreeTextcuvintele vizibile ale lui, și returnează 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');

Aplatizarea adnotărilor

Annotation.Flatten() încorporează aspectul /AP al unei adnotări direct în fluxul de conținut al paginii la /Rect, apoi îl elimină din /Annots. Rezultatul este un conținut permanent, static — nu mai este o adnotare distinctă pe care un vizualizator o poate face clic, edita sau ascunde.

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

Sfaturi și bune practici

  • Apelă Flatten() pe obiectul returnat direct de apelul Add*() — o adnotare obținută prin recitirea page.Annotations ulterior este o referință de obiect diferită.
  • SearchAnnotationText() și SearchAnnotations() acoperă texte diferite: rulează ambele dacă trebuie să găsești o frază indiferent dacă a fost tastată într-o notă sau desenată pe pagină.
  • Cele patru metode de marcare (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut) generează automat aspectul lor /AP — nu este necesar niciun desen manual în fluxul de conținut.
  • Criptarea supraviețuiește unui ciclu complet: adnotările adăugate înainte de Document.Save() cu o opțiune encrypt rămân valabile după ce documentul este redeschis și decriptat.

Probleme comune

ProblemăCauzăRemediere
page.Annotations.find() returnează undefined pentru o adnotare pe care tocmai ai adăugat-oSe caută un tablou învechit capturat înainte ca adnotarea să fie adăugatăRecitește page.Annotations după apelul Add*(), sau folosește direct identificatorul pe care apelul l-a returnat
SearchAnnotationText() nu găsește nimic pentru textul vizibil pe paginăTextul este trasat de adnotare (de exemplu, corpul unui FreeText), nu este transportat în /ContentsFolosește SearchAnnotations() în schimb — se potrivește cu textul trasat
Adnotarea apare în continuare editabilă după Flatten()Flatten() a fost apelat pe o copie în loc de mânerul pe care l-a returnat Add*()Apelează Flatten() pe obiectul returnat direct de metoda de creare

FAQ

Care este diferența dintre SearchAnnotationText și SearchAnnotations?

SearchAnnotationText() potrivește textul unei adnotări carries — /Contents, /T (autor), sau /Subj — cum ar fi corpul unei notițe adezive. SearchAnnotations() potrivește textul unei adnotări draws pe pagină, cum ar fi un FreeText’s cuvinte vizibile. Cele două sunt disjuncte: o potrivire într-una nu va apărea în cealaltă.

Cum pot face o adnotare permanentă și non-interactivă?

Apelă Flatten() pe identificatorul Annotation returnat de metoda Add*() care a creat-o. Aceasta încorporează aspectul său în fluxul de conținut al paginii și o elimină din /Annots.

Ce subtipuri de adnotări sunt suportate?

Page expune metode de creare pentru marcarea textului (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), note și apeluri (AddTextNote, AddFreeText, AddCaret), linkuri (AddLink), forme (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), cerneală liberă (AddInk), ștampile (AddStamp) și atașamente de fișiere (AddFileAttachment).

Cum pot să enumăr toate adnotările deja prezente pe o pagină?

Citește page.Annotations, un array de handle-uri Annotation. Fiecare expune Subtype, Rect, Color, Contents și celelalte proprietăți comune, astfel încât să le poți filtra sau inspecta cu metode standard de array.


API Reference Rezumat

Clasă/MetodăDescriere:
AnnotationMâner de bază pentru orice adnotare; expune Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity
Annotation.Flatten()Încorporează aspectul adnotării în conținutul static al paginii
TextAnnotationUn mâner de notiță adezivă /Text; adaugă Icon, Open, Author
StampAnnotationUn mâner de ștampilă de cauciuc /Stamp; adaugă StampName
MarkupAnnotationUn mâner de marcare a textului (Highlight/Underline/StrikeOut/Squiggly); adaugă MarkupType, QuadPoints
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly()Creează o adnotare de marcare a textului peste /QuadPoints
Page.AddTextNote()Creează o adnotare tip sticky-note
Page.AddLink()Creează un link clicabil cu un URI sau o acțiune internă
Page.AnnotationsFiecare Annotation de pe pagină, ca un tablou
Page.SearchAnnotationText()Găsește textul pe care îl conține o adnotare (/Contents, /T, /Subj)
Page.SearchAnnotations()Găsește textul pe care o adnotare îl trasează pe pagină

Vezi și:

 Română