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 apelulAdd*()— o adnotare obținută prin recitireapage.Annotationsulterior este o referință de obiect diferită. SearchAnnotationText()șiSearchAnnotations()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țiuneencryptră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-o | Se 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 /Contents | Foloseș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: |
|---|---|
Annotation | Mâ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 |
TextAnnotation | Un mâner de notiță adezivă /Text; adaugă Icon, Open, Author |
StampAnnotation | Un mâner de ștampilă de cauciuc /Stamp; adaugă StampName |
MarkupAnnotation | Un 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.Annotations | Fiecare 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ă |