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 بدلاً من أن يرسم — ملاحظة /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 لتعليق أضفته للتوالبحث في مصفوفة قديمة تم التقاطها قبل إضافة التعليقأعد قراءة page.Annotations بعد استدعاء Add*()، أو استخدم المقبض الذي أعادته الاستدعاء مباشرة
SearchAnnotationText() لا يجد شيئًا للنص المرئي على الصفحةالنص يتم سحبه بواسطة التعليق (مثال: جسم FreeText)، وليس موجودًا في /Contentsاستخدم SearchAnnotations() بدلاً من ذلك — فهو يطابق النص المسحوب
ما زال التعليق التوضيحي يظهر قابلًا للتحرير بعد Flatten()تم استدعاء Flatten() على نسخة بدلاً من المؤشر الذي أرجعه Add*()استدعِ Flatten() على الكائن الذي تم إرجاعه مباشرةً بواسطة طريقة الإنشاء

FAQ

ما الفرق بين SearchAnnotationText و SearchAnnotations؟

SearchAnnotationText() يطابق نصًا في توضيح carries — /Contents, /T (author)، أو /Subj — مثل محتوى الملاحظة اللاصقة. SearchAnnotations() يطابق نصًا في توضيح draws على الصفحة، مثل a FreeText’s الكلمات الظاهرة. الاثنين منفصلان: المطابقة في أحدهما لن تظهر في الآخر.

كيف أجعل التعليقة دائمة وغير تفاعلية؟

استدعِ Flatten() على مقبض 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()ابحث عن النص الذي تُضيفه التعليقة على الصفحة

انظر أيضاً

 العربية