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()متن را پیدا کنید که یک حاشیه‌نویسی روی صفحه می‌کشد

همچنین ببینید:

 فارسی