Annotations
הסברים
דף זה מכסה יצירה, קריאה, חיפוש והשטחת הסברים של PDF. Page חושפת שיטה Add*() אחת לכל תת-סוג של הסבר, שכל אחת מחזירה מצביע Annotation חי; מחלקת הבסיס Annotation ותתי-המחלקות שלה (TextAnnotation, StampAnnotation, MarkupAnnotation ואחרות) חושפות את המאפיינים של ההסבר לקריאה ועריכה.
יצירת הסברים מסוג סימון, פתק וקישור
ארבעת שיטות סימון הטקסט — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() ו-Page.AddStrikeOut() — מקבלות מערך quads (/QuadPoints) ומחזירות MarkupAnnotation. Page.AddLink() יוצרת אזור לחיצה עם URI או פעולה פנימית, ו-Page.AddTextNote() מוסיפה אייקון פתק דביק שפותח חלונית קופצת עם טקסט contents, ומחזירה 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 גם חושפת שיטות צורה ויד חופשית — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() ו-AddStamp() — שכל אחת מחזירה את מצביע ההסבר המתאים לתת-סוג הזה, ויוצרת את המראה /AP שלו אוטומטית.
קריאת והצגת הסברים
page.Annotations הוא מערך של כל הAnnotation בעמוד. כל הסבר, ללא תלות בתת-הסוג, חושף את Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden ו-Opacity; תתי-הסוג מוסיפים שדות משלהם, כגון StampAnnotation.StampName או MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}חיפוש טקסט של ההערה
Page.SearchAnnotationText() and Page.SearchAnnotations() הם מופרדים במכוון. SearchAnnotationText() מוצא התאמות בטקסט ובהערה carries במקום לצייר — של ההערה /Contents, מחברו (/T), או נושא שלו (/Subj) — ומחזיר AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() מוצא התאמות בטקסט ובהערה draws, כגון FreeTextמילים גלויות של ’s, ומחזירה 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');שטיחת ההערות
Annotation.Flatten() משלב את המראה של /AP של ההערה ישירות לתוך זרם התוכן של העמוד ב-/Rect, ואז מסיר אותה מ-/Annots. התוצאה היא תוכן קבוע, סטטי — לא עוד הערה נפרדת שהצופה יכול ללחוץ עליה, לערוך או להסתיר.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();טיפים ושיטות מומלצות
- קרא ל-
Flatten()על האובייקט שהוחזר ישירות על ידי קריאתAdd*()— הערה שהושגה על-ידי קריאה מחדש שלpage.Annotationsלאחר מכן היא הפניה לאובייקט שונה. SearchAnnotationText()ו-SearchAnnotations()מכסים טקסט שונה: הרץ את שניהם אם אתה צריך למצוא ביטוי ללא תלות אם הוא נכתב בפתק או צויר על העמוד.- ארבעת שיטות הסימון (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) מייצרות את המראה של/APבאופן אוטומטי — אין צורך בציור ידני של זרם התוכן. - הצפנה שורדת מסע סיבוב: ההערות שנוספו לפני
Document.Save()עם אפשרותencryptנשארות תקפות לאחר שהמסמך נפתח מחדש ומפוענח.
בעיות נפוצות
| בעיה | סיבה | תיקון |
|---|---|---|
page.Annotations.find() מחזיר undefined עבור ההערה שהוספת זה עתה | מחפש מערך מיושן שנלכד לפני שההערה נוספה | קרא מחדש את page.Annotations אחרי קריאת Add*(), או השתמש במזהה שהחזרה הקריאה ישירות |
SearchAnnotationText() לא מוצא דבר עבור טקסט גלוי בעמוד | הטקסט נוצר על ידי ההערה (למשל, גוף של FreeText), ולא מועבר ב-/Contents | השתמש ב-SearchAnnotations() במקום — הוא תואם לטקסט שנוצר |
ההערה עדיין מופיעה כניתנת לעריכה לאחר Flatten() | Flatten() נקרא על עותק במקום על המזהה Add*() שהוחזר | קרא ל-Flatten() על האובייקט שהוחזר ישירות על-ידי שיטת היצירה |
FAQ
מה ההבדל בין SearchAnnotationText ל-SearchAnnotations?
SearchAnnotationText() מתאים טקסט של הערה carries — /Contents, /T (author), או /Subj — כגון גוף של פתק הדבקה. SearchAnnotations() מתאים טקסט להערה draws בדף, כגון FreeTextמילים נראות של ’s. השניים נפרדים: התאמה באחד לא תופיע באחר.
איך אני עושה שההערה תהיה קבועה ולא אינטראקטיבית?
קרא ל-Flatten() על ה-Annotation handle שהוחזר על ידי השיטה Add*() שיצרה אותו. פעולה זו משטחת את המראה שלו אל זרם תוכן העמוד ומסירה אותו מ-/Annots.
אילו תתי-סוגים של הערות נתמכים?
Page מציג שיטות יצירה לסימון טקסט (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), פתקים והדגשות (AddTextNote, AddFreeText, AddCaret), קישורים (AddLink), צורות (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), דיו חופשי (AddInk), חותמות (AddStamp), וקבצי צרופות (AddFileAttachment).
איך אני מציג את כל ההסברים שכבר קיימים בדף?
קרא את page.Annotations, מערך של מצביעי Annotation. כל אחד חושף את Subtype, Rect, Color, Contents, והמאפיינים המשותפים האחרים, כך שניתן לסנן או לבדוק אותם עם שיטות מערך סטנדרטיות.
API Reference תקציר
| מחלקה/מתודה | תיאור |
|---|---|
Annotation | מטפל בסיסי על כל הערה; חושף Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | הטמע את מראה ההערה בתוכן דף סטטי |
TextAnnotation | ידית פתק דביק /Text; מוסיפה Icon, Open, Author |
StampAnnotation | ידית חותמת גומי /Stamp; מוסיפה StampName |
MarkupAnnotation | ידית סימון טקסט (Highlight/Underline/StrikeOut/Squiggly); מוסיפה MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | צור סימון טקסט על /QuadPoints |
Page.AddTextNote() | צור הערת פתק דביק |
Page.AddLink() | צור קישור לחיץ עם URI או פעולה פנימית |
Page.Annotations | כל Annotation על העמוד, כמערך |
Page.SearchAnnotationText() | מצא את הטקסט שההערה נושאת (/Contents, /T, /Subj) |
Page.SearchAnnotations() | מצא טקסט שההערה מציירת על הדף |