التعليق التوضيحي على ملفات PDF

يعرض pdf ملف PDF داخل المتصفح باستخدام PDF.js ويضع سطح التعليق التوضيحي على الصفحة المعروضة بدلًا من نص مستخرج مسبقًا. يرى المُعلِّق المستند الحقيقي بأعمدته وجداوله وأشكاله وفواصل صفحاته كما هي، ويضع التسميات في مكانها. يأخذ هذا العرض مفتاحًا مطلوبًا واحدًا، وهو الحقل الذي يحمل مسار ملف PDF أو عنوانه، وكل ما عداه خيار عرض.

instance_display:
  fields:
    - key: pdf
      type: pdf
      label: "Document"
      display_options:
        view_mode: scroll
        max_height: 760
        zoom: page-width

يأخذ view_mode القيم scroll أو paginated أو side-by-side. يكدّس التمرير المتواصل كل الصفحات في حاوية واحدة، وهو ما يهم عندما يحتاج تعليق توضيحي إلى الامتداد عبر فاصل صفحات. أما العرض المُصفَّح فيُظهر صفحة واحدة في كل مرة مع عناصر تحكم للتنقل، ويناسب المستندات الطويلة التي يعمل فيها المُعلِّق صفحة بصفحة.

أنماط التعليق التوضيحي الثلاثة

يحدد annotation_mode ما يمكن للمُعلِّق رسمه، وهو الخيار الذي يغيّر المهمة نفسها لا مظهرها. القيمة الافتراضية هي span.

يعتمد نمط span على احتواء ملف PDF على طبقة نص، وهو ما يتحقق في أي ملف PDF ناتج عن معالج نصوص أو نظام تنضيد، ولا يتحقق في ملف ممسوح ضوئيًا. أما نمط bounding_box فلا يعتمد عليها، لذا يمكن تسمية صفحة ممسوحة ضوئيًا حسب المنطقة دون أي استخراج للنص على الإطلاق.

لأن العرض pdf يربط المقاطع عبر طبقة نص PDF.js بدلًا من غلاف .text-content الذي تستخدمه أنواع العرض الأخرى، فهو لا يقبل الراية span_target. ويظل التعليق التوضيحي على المقاطع يعمل، من خلال طبقة النص الخاصة بملف PDF.

الربط عبر الصفحات

نمط link مخصص للعلاقات التي تمتد عبر الصفحات، مثل ادعاء في الصفحة 2 يستند إلى شكل في الصفحة 9. يضع المُعلِّق المرتكزات أولًا، ثم يرسم روابط مصنّفة بينها، ويسجّل Potato المرتكزات والروابط تحت أسماء مخططات منفصلة.

instance_display:
  fields:
    - key: pdf
      type: pdf
      label: "Document"
      display_options:
        annotation_mode: link
        view_mode: scroll
        enable_text_anchors: true
        enable_region_anchors: true
        anchor_schema: pdf_anchors
        link_schema: pdf_links
        anchor_labels:
          - name: claim
            color: "#dc2626"
          - name: figure
            color: "#2563eb"
        link_types:
          - name: refers_to
            directed: true
            color: "#dc2626"
            allowed_source_labels: [claim]
            allowed_target_labels: [figure]

يقيّد allowed_source_labels وallowed_target_labels المرتكزات التي يمكن لنوع رابط أن يصل بينها، وبهذا يتحول التوجيه الإرشادي إلى قاعدة تفرضها الواجهة بدلًا من قاعدة على المُعلِّق أن يتذكرها. الرابط refers_to المُعدّ كما في الأعلى لا يمكن أن يبدأ إلا من claim ولا أن ينتهي إلا عند figure، لذا يُرفض أي رابط يُرسم من شكل عائدًا إلى ادعاء. اضبط directed: false لعلاقة متناظرة مثل same_as.

المرتكزات نوعان، ويمكن إيقاف كلٍّ منهما على حدة. يتيح enable_text_anchors تمييز مقطع نصي، ويتيح enable_region_anchors رسم مربع منطقة، وهو ما يحتاجه شكل أو جدول. ويأتي مثال كامل مشروح في المستودع الأصلي ضمن examples/advanced/pdf-link-scroll/.

المستندات الممسوحة ضوئيًا وOCR

ocr معطَّل افتراضيًا، ولا يقرأه Potato إلا في نمط link. وعند ضبطه، تُستخرج الكلمات على الخادم وتُستخدم لبناء طبقة نص على العميل، فيصبح بإمكان ملف ممسوح ضوئيًا بلا نص مضمَّن أن يحمل مرتكزات نصية. يأخذ الخيار القيم false أو true أو auto، ويرفض Potato أي قيمة أخرى.

instance_display:
  fields:
    - key: pdf
      type: pdf
      display_options:
        annotation_mode: link
        ocr: auto
        ocr_dpi: 200
        ocr_lang: eng

تختلف الإعدادات الثلاثة في توقيت تشغيل المرور. تستخدم false طبقة النص المضمَّنة وحدها، وتشغّل true عملية OCR دائمًا، بينما تلجأ auto إلى OCR فقط عندما تعود طبقة النص المضمَّنة فارغة. فضّل auto على مجموعة مختلطة من الملفات، لأن OCR بطيء ويتطلب تثبيت Tesseract. يتحكم ocr_dpi في الدقة التي تُحوَّل بها كل صفحة إلى صورة نقطية قبل أن يقرأها OCR، ورفعها يكلف وقتًا في كل صفحة. يأخذ ocr_lang رمز لغة Tesseract وقيمته الافتراضية eng.

خيارات العرض

ملفات Word وMarkdown

يستخدم ملف DOCX أو Markdown العرض document بدلًا من ذلك، وهو يحافظ على بنية العناوين والفقرات في المستند ويقبل span_target. ويقرأ annotation_mode بقيمة span أو bounding_box، ويبني show_outline جدول محتويات من العناوين الواردة في المتن. يمرر Potato الترميز المُصيَّر عبر قائمة سماح قبل وصوله إلى المُعلِّق، فيُجرَّد أي حقل في المجموعة يحمل وسمًا قابلًا للتنفيذ بدلًا من تشغيله.

instance_display:
  fields:
    - key: report
      type: document
      label: "Report"
      display_options:
        show_outline: true
        max_height: 600

قراءات إضافية

• عرض العنصر يسرد كل أنواع العرض وأيها يقبل أهداف المقاطع.
• التعليق التوضيحي على المقاطع يغطي خيارات التسمية التي يأخذها مخطط المقاطع.
• كيفية التعليق التوضيحي على المستندات يعالج مهمة مراجعة مستند من أولها إلى آخرها.
• للاطلاع على تفاصيل التنفيذ، انظر مستندات المصدر.