المقدمة

المقالة المقدمة تغطي التعليقات التوضيحية باختصار: التظليل، التسطير، الملاحظات اللاصقة، والطوابع، التي تُضاف عبر Page.AddHighlight()، Page.AddUnderline()، وطرق مشابهة. وهذا جزء صغير مما يدعمه Page فعليًا — معرض التعليقات التوضيحية في هذه المكتبة يغطي التعليمات البرمجية، الأشكال اليدوية، الروابط مع تنقل حقيقي وإجراءات إرسال النماذج، والبحث، وكل ذلك يمكن الوصول إليه مباشرةً من Page.

تستعرض هذه المشاركة باقي ذلك السطح: طرق التعليقات التوضيحية للأشكال واليد الحرة، وما يمكن لإجراء تعليق توضيحي Link أن يفعله فعليًا، والطريقتين المختلفتين للبحث في محتوى التعليق التوضيحي اعتمادًا على ما إذا كان النص الذي تبحث عنه موجودًا في مظهر التعليق أو في تعليقه /Contents.

كل طريقة تعليق توضيحي تُعيد مقبضًا مُصنّفًا يقتصر على التعليق الذي تم إنشاؤه للتو، ويمكن قراءة كل تعليق على صفحة لاحقًا عبر 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) هو المتطلب الوحيد في وقت التنفيذ، ولا توجد للحزمة أي تبعيات طرف ثالث أخرى.

البدء

الموارد ذات الصلة