مقدمه

پست introductory post به‌طور مختصر به حاشیه‌نویسی‌ها می‌پردازد: برجسته‌سازی‌ها، زیرخط‌گذاری‌ها، یادداشت‌های چسبی و مهرها که از طریق Page.AddHighlight()، Page.AddUnderline() و روش‌های مشابه اضافه می‌شوند. این تنها بخشی کوچک از آنچه یک Page واقعاً پشتیبانی می‌کند است — گالری حاشیه‌نویسی در این کتابخانه شامل نشانه‌گذاری، شکل‌های دستی، پیوندهایی با ناوبری واقعی و عملیات ارسال فرم، و جستجو می‌شود، که همه به‌صورت مستقیم از Page قابل دسترسی هستند.

این پست بقیهٔ آن سطح را مرور می‌کند: روش‌های حاشیه‌نویسی شکل و دستی، آنچه عمل یک حاشیه‌نویسی Link می‌تواند واقعاً انجام دهد، و دو روش مختلف برای جستجوی محتوای حاشیه‌نویسی بسته به این‌که متن مورد نظر شما در ظاهر حاشیه‌نویسی یا در /Contents comment زندگی می‌کند.

هر روش حاشیه‌نویسی یک دستگیرهٔ تایپ‌شده بر‌پایهٔ حاشیه‌نویسی که تازه ایجاد کرده است برمی‌گرداند، و هر حاشیه‌نویسی در صفحه پس از آن از طریق page.Annotations قابل خواندن است.

چه چیزهایی گنجانده شده است

حاشیه‌نویسی‌های نشانه‌گذاری

همهٔ Page.AddHighlight()، Page.AddUnderline()، Page.AddSquiggly() و Page.AddStrikeOut() همان شکل گزینه‌ها را می‌پذیرند — مجموعه‌ای از نقاط چهارگانه که ناحیهٔ متن را علامت‌گذاری می‌کند و یک رنگ اختیاری — و هر چهار مورد یک MarkupAnnotation برمی‌گردانند. نقاط چهارگانه معمولاً از یک جستجوی متن یا از یک مستطیل متن شناخته‌شده استخراج می‌شوند.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

یادداشت‌ها و متن‌های مستقل

Page.AddTextNote() یک نماد کلاسیک یادداشت چسبان اضافه می‌کند که هنگام کلیک یک پنجرهٔ پاپ-آپ نظر باز می‌کند و یک TextAnnotation برمی‌گرداند. Page.AddFreeText() به‌جای آن، متن خود را مستقیماً روی صفحه داخل یک جعبهٔ دارای حاشیه می‌کشد، با اندازهٔ قلم، تراز و رنگ پر کردن مخصوص خود — مفید برای نکات برجسته‌ای که باید بدون باز کردن چیزی قابل مشاهده باشند.

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

اشکال و جوهر دست‌خط

Page.AddSquare() و Page.AddCircle() یک مستطیل یا بیضی دارای حاشیه می‌کشند، هر کدام با پر کردن داخلی اختیاری. Page.AddLine() خطی مستقیم بین دو نقطه می‌کشد، با سبک‌های سرپیکان قابل انتخاب به‌صورت مستقل (startEnding/endEnding، مثلاً 'OpenArrow'/'ClosedArrow') در هر انتها. Page.AddPolygon() و Page.AddPolyline() اشکال چندنقطه‌ای بسته و باز را از یک لیست صاف از مختصات می‌کشند، و Page.AddInk() یک یا چند ضربه قلم دست‌خط را به‌صورت paths از فهرست‌های نقطه‌ای ثبت می‌کند.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

لینک‌ها و اقدامات آن‌ها

Page.AddLink() یک LinkAnnotation برمی‌گرداند که action آن تعیین می‌کند هنگام کلیک چه اتفاقی می‌افتد: { type: 'uri', uri: '...' } یک URL خارجی را باز می‌کند، { type: 'goto', page: N } به صفحه‌ای داخل همان سند می‌پرهیزد، و { type: 'submit', url: '...', format: 'html' } مقادیر فعلی فیلدهای فرم را به یک نقطهٔ انتهایی ارسال می‌کند. یک شمارهٔ صفحهٔ goto خارج از محدوده یا یک شیء اقدام خراب، در زمان ایجاد رد می‌شود نه این‌که به‌صورت ساکت پذیرفته شود.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

جستجوی محتوای حاشیه‌نویسی

دو روش متفاوت متن حاشیه‌نویسی را جستجو می‌کنند و آن‌ها عمداً جدا هستند: Page.SearchAnnotations() متن ظاهر خود یک حاشیه‌نویسی را جستجو می‌کند رسم می‌کند — برچسب قابل مشاهده روی یک FreeText یا مهر، به عنوان مثال — در حالی که Page.SearchAnnotationText() متن موجود در حاشیه‌نویسی را جستجو می‌کند /Contents ورودی، مانند بدنهٔ نظر یک یادداشت چسبان. یک تطبیق در یکی لزوماً به معنای تطبیق در دیگری نیست.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

یادداشت‌هایی که دیگر لازم نیستند می‌توانند مستقیماً با Page.RemoveAnnotation() حذف شوند، با عبور از شناسهٔ یادداشت یا دیکشنری زیرین آن.

شروع سریع

پکیج را نصب کنید، سپس یک هایلایت، یک لینک و یک یادداشت چسبی به صفحهٔ موجود اضافه کنید:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

قالب‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

منبع باز و مجوزدهی

Aspose.PDF FOSS برای TypeScript تحت مجوز MIT منتشر شده است، با منبع منتشر شده در GitHub. هیچ علامت آب‌نمای ارزیابی، محدودیت استفاده یا فایل مجوز جداگانه‌ای برای مدیریت وجود ندارد و این کتابخانه می‌تواند در محصولات تجاری بدون حق امتیاز استفاده شود.

این پکیج در حال حاضر نسخهٔ 0.1.0 دارد که نشان‌دهندهٔ توسعه فعال در مرحلهٔ اولیه است. Node.js (>=22) تنها نیازمندی زمان اجرا است و این پکیج هیچ وابستگی شخص ثالث دیگری ندارد.

شروع به کار

منابع مرتبط