چگونه با حاشیه‌نویسی‌ها در TypeScript کار کنیم

این راهنما نشان می‌دهد که چگونه حاشیه‌نویسی‌های PDF را با Aspose.PDF FOSS برای TypeScript اضافه، مسطح و جستجو کرد. کلاس Page برای هر زیرنوع حاشیه‌نویسی یک متد Add* ارائه می‌دهد — علامت‌گذاری (هایلایت، زیرخط، خط‌خورده، موج‌دار)، اشکال (مربع، دایره، خط، چندضلعی، جوهر)، متن (یادداشت چسبان، متن آزاد) و لینک‌ها — که هر کدام یک دستگیرهٔ Annotation تایپ‌شده برمی‌گردانند که می‌توان بعداً آن را خواند یا مسطح کرد. این کتابخانه نیاز به Node.js نسخهٔ ۲۲ یا بالاتر دارد.

راهنمای گام‌به‌گام

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';

import { Document, Page } from '@asposefoss/pdf';

import { Document } from '@asposefoss/pdf';

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

page.AddHighlight({
  quads: [72, 700, 300, 700, 72, 685, 300, 685],
  color: [1, 1, 0],
  contents: 'Yellow highlight',
});
page.AddUnderline({
  quads: [72, 660, 300, 660, 72, 645, 300, 645],
  color: [0, 0, 1],
});
page.AddStrikeOut({
  quads: [72, 620, 300, 620, 72, 605, 300, 605],
  color: [1, 0, 0],
});

doc.WriteTo('annotated.pdf');

page.AddSquare({ rect: [100, 500, 220, 560], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [250, 500, 370, 560], color: [0, 0.5, 0], width: 2 });
page.AddLine({
  line: [100, 470, 370, 470],
  color: [0, 0, 0.7],
  width: 2,
  startEnding: 'OpenArrow',
  endEnding: 'ClosedArrow',
});
page.AddInk({
  paths: [[100, 400, 130, 430, 160, 390, 190, 420]],
  color: [0.6, 0, 0.6],
  width: 2,
});

page.AddTextNote({
  rect: [400, 700, 420, 720],
  icon: 'Note',
  author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [400, 600, 550, 660],
  contents: 'FreeText sample',
  fontSize: 10,
  align: 'center',
  fill: [1, 1, 0.8],
  width: 1,
});

const note = page.AddFreeText({
  rect: [210, 535, 470, 590],
  contents: 'Sticky note — flattened into the page.',
  fontSize: 11,
  align: 'left',
});

note.Flatten(); // -> boolean; bakes the annotation, unwires itself from /Annots

const metadataHits = page.SearchAnnotationText('confidential');
for (const hit of metadataHits) {
  console.log(hit.key, hit.value); // e.g. 'Contents', 'confidential'
}

const renderedHits = page.SearchAnnotations('confidential');
console.log(renderedHits.length);

مشکلات رایج و راه‌حل‌ها

Page.AddHighlight() (یا روش نشانه‌گذاری دیگری) در مکان اشتباه رسم می‌شود. quads یک آرایه تخت 8 عددی است (x1,y1,x2,y2,x3,y3,x4,y4), نه یک rect — عبور یک مستطیل ۴ عددی یک چهارضلعی نابرابری یا گمشده تولید می‌کند. برای هر خط از متن هایلایت‌شده یک چهارضلعی بسازید.

یک حاشیه‌نویسی صاف‌شده همچنان قابل کلیک است. Flatten() باید بر روی شیء بازگردانده‌شده توسط Add* فراخوانی، و سند باید ذخیره شود (doc.WriteTo() / doc.Save()) پس از صاف‌سازی — تغییر فقط در حافظه وجود دارد تا زمانی که فایل دوباره نوشته شود.

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

علامت‌های Redaction هنگام جستجوی حاشیه‌نویسی‌ها نشان داده نمی‌شوند. Page.AddRedact() یک مورد ایجاد می‌کند RedactAnnotation، یک زیرنوع متمایز از حاشیه‌نویسی‌های markup/shape/text که در اینجا پوشش داده شده‌اند — ببینید Redaction راهنما.

سوالات متداول

چند زیرنوع حاشیه‌نویسی توسط Page پشتیبانی می‌شود؟

کتابخانه ظاهرهای حاشیه‌نویسی برای علامت‌گذاری (هایلایت، زیرخط، خط‌خورده، موج‌دار)، اشکال (مربع، دایره، خط، چندضلعی، جوهر)، متن (یادداشت چسبان، متن آزاد)، لینک‌ها و مهرها را تولید می‌کند — به‌علاوه حاشیه‌نویسی‌های پیوست فایل و حذف، که در راهنمای‌های آموزشی مخصوص خود پوشش داده شده‌اند.

آیا می‌توانم حاشیه‌نویسی‌های موجود بر روی یک صفحه را بخوانم؟

بله — Page.Annotations حاشیه‌نویسی‌های موجود را به‌صورت آرایه‌ای از دستگیره‌های تایپی برمی‌گرداند که می‌توانید آن‌ها را بررسی، ویرایش یا صاف کنید، و Page.RemoveAnnotation(a) یکی را حذف می‌کند.

تفاوت صاف‌کردن یک حاشیه‌نویسی و اعمال حذف (Redaction) چیست؟

Flatten() حاشیه‌نویسی را appearance به صفحه وارد می‌کند و شیء annotation را حذف می‌کند، اما هر متن یا محتوای تصویری زیر آن دست نخورده می‌ماند. ApplyRedactions() به‌صورت مخرب جریان محتوا را بازنویسی می‌کند به‌طوری که محتوای تحت پوشش خود حذف می‌شود — برای جزئیات به راهنمای Redaction مراجعه کنید.

آیا حاشیه‌نویسی‌ها پس از یک دور ذخیره/باز کردن حفظ می‌شوند؟

بله — حاشیه‌نویسی‌های اضافه شده قبل از doc.WriteTo() / doc.Save() در PDF نوشته می‌شوند و در Document.Open() / Document.OpenFile() بعدی به‌درستی خوانده می‌شوند.

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

• هسته API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base