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 بهجای کشیدن — یک یادداشت’s /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 برمیگرداند | در حال جستجوی آرایهای کهنه که قبل از افزودن حاشیهنویسی گرفته شده است | پس از فراخوانی Add*()، page.Annotations را دوباره بخوانید، یا بهصورت مستقیم از دستگیرهای که فراخوانی برگرداند استفاده کنید |
SearchAnnotationText() برای متنی که در صفحه قابل رؤیت است، هیچچیزی پیدا نمیکند | متن توسط حاشیهنویسی کشیده میشود (مثلاً بدنهٔ FreeText)، نه اینکه در /Contents حمل شود | بهجای آن از SearchAnnotations() استفاده کنید — این متن کشیدهشده را مطابقت میدهد |
حاشیهنویسی پس از Flatten() همچنان بهصورت قابل ویرایش ظاهر میشود | Flatten() روی یک کپی فراخوانی شد نه روی handle ای که Add*() برگرداند | متد Flatten() را بر روی شیئی که مستقیماً توسط متد سازنده برگردانده میشود، فراخوانی کنید |
FAQ
تفاوت بین SearchAnnotationText و SearchAnnotations چیست؟
SearchAnnotationText() متنهای منطبق یک حاشیهنویسی carries — /Contents, /T (author)، یا /Subj — مانند بدنه یک یادداشت چسبان. SearchAnnotations() متنهای منطبق یک حاشیهنویسی draws در صفحه، مانند یک FreeTextکلمات قابل مشاهده. این دو جدا هستند: مطابقت در یکی در دیگری ظاهر نخواهد شد.
چگونه میتوان یک حاشیهنویسی را دائمی و غیرقابل تعامل ساخت؟
متد Flatten() را بر روی handle Annotation که توسط متد 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() | متن را پیدا کنید که یک حاشیهنویسی روی صفحه میکشد |