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