نمط مرجع الحاشية السفلية وجسمها عبر Connect

نمط مرجع الحاشية السفلية وجسمها عبر ⁨Connect⁩

لمحة سريعة

صيِّر مراجع الحواشي السفلية وأجسامها عبر ⁨Connect⁩ بحيث تعرض شجرة البنية أدوار الحواشي السفلية في ⁨PDF 2.0.⁩ تصبح العلامة المضمَّنة مرجع ⁨footnote/endnote⁩، ويصبح نص الحاشية السفلية جسم الملاحظة، مع مرجع خلفي متبادل بينهما. تؤدي ثلاثة أشكال من ⁨HTML⁩ إلى المخرَج نفسه: رابط داخل نص مرتفع، ودور ⁨Accessible Rich Internet Applications⁩ (⁨ARIA⁩) صريح role="doc-noteref"، وحاوية جسم <aside class="footnote">. يستخدم التحقق أداة إمكانية الوصول من فئة ⁨Pro⁩؛ يكتشفها ⁨NextPDF⁩ باستخدام class_exists() ولا يسجّلها إلا عند تثبيت nextpdf/premium إلى جانب الخادم.

تعني النتيجة الناجحة من أداة إمكانية الوصول إجراء فحص لإمكانية الوصول، وليست شهادة مطابقة مستقلة.

التثبيت

composer require nextpdf/server

تحقّق من توفر أداة إمكانية الوصول في ⁨Pro⁩ باستخدام استدعاء tools/list؛ راجع /⁨connect/tool-catalog/.⁩

نظرة عامة مفاهيمية

يحدد ⁨PDF 2.0⁩ أنواع بنية مخصصة لـ ⁨footnote/endnote⁩ والعلاقة بين المرجع وجسمه (⁨PDF/UA-2⁩ §8.2.5). يجب إقران مرجع الحاشية السفلية بجسمه (⁨PDF/UA-2⁩ §8.2.5)، كي يستطيع قارئ الشاشة الإعلان عن المرجع وتتبُّع الرابط لقراءة الملاحظة. يجب أن يكون كلٌّ من المرجع والجسم متاحًا عبر شجرة البنية (⁨PDF/UA-2⁩ §8.2.4).

يتعرّف خط الأنابيب إلى ثلاثة أشكال للمرجع:

1. <sup><a href="#fn-N">N</a></sup> — نمط مختصر لرابط داخل نص مرتفع.
2. <sup role="doc-noteref" aria-describedby="fn-N">N</sup> — دور ⁨Digital Publishing Accessible Rich Internet Applications⁩ (⁨DPUB-ARIA⁩) صريح؛ تُمرَّر aria-describedby على أنها هدف المرجع الخلفي.
3. <aside class="footnote" id="fn-N">…</aside> (أو role="doc-footnote") — حاوية الجسم، تُنتَج على أنها جسم الملاحظة مع مرجع داخلي يعود إلى المرجع المطابق.

واجهة ⁨API⁩

تحقّق من أسماء الأدوات في السجل قيد التشغيل باستخدام tools/list. الكتالوج المرجعي هو /⁨connect/tool-catalog/.⁩ تستخدم هذه الوصفة أدوات المستند و⁨HTML⁩ الأساسية، إضافةً إلى فحص إمكانية الوصول في ⁨Pro⁩، ولا تعيد تعداد الأدوات.

نموذج التعليمات البرمجية — بداية سريعة

أنشئ مستندًا موسومًا مع تحديد اللغة، ثم أضف مرجعًا بنمط الرابط المختصر:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Footnote Patterns", "language": "en" }
  }
}

نموذج التعليمات البرمجية — الإنتاج

أنشئ المرجعين والجسمين معًا ضمن إضافة ⁨HTML⁩ واحدة، ثم شغّل الفحص:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

يُظهر فحص إمكانية الوصول أدوار ⁨reference/body⁩ المقترنة والمراجع الخلفية المتبادلة.

الحالات الحدّية والمزالق

• مرجع دون جسم (أو جسم دون مرجع) يرصدُه الفحص؛ فكل مرجع يحتاج إلى جسم مطابق، والعكس صحيح.
• عدم تطابق id بين aria-describedby وid الجسم يترك الزوج دون حل (مع مراعاة حالة الأحرف).
• رابط نص مرتفع إلى ⁨URL⁩ خارجي يُنتج رابطًا عاديًا، وليس مرجعًا لحاشية سفلية؛ استخدم الدور الصريح لهدف خارجي.
• <aside> مجردة دون class/⁨role⁩ تُعامَل بوصفها معلمًا، وليست جسم ملاحظة. أضف class="footnote" أو role="doc-footnote".
• الأداة غائبة. من دون nextpdf/premium، لا تُسجَّل أداة إمكانية الوصول في ⁨Pro⁩، لذا يفشل التحقق بخطأ أداة غير معروفة.

الأداء

ميزانية البيانات الأولية حدّ توثيقي؛ أما إقران الحواشي السفلية فهو جزء من تمريرة البنية العادية.

ملاحظات الأمان

لا توجد اعتبارات إضافية تتجاوز إرشادات نقل ⁨Connect⁩ العامة.

المطابقة

تخطيط ⁨PDF/UA-2⁩

الادعاء	البند	⁨reference_id⁩
أنواع بنية ⁨footnote/endnote⁩ وعلاقة ⁨reference/body⁩	⁨PDF/UA-2⁩ §8.2.5
مرجع الحاشية السفلية مقترن بجسمه	⁨PDF/UA-2⁩ §8.2.5
المرجع والجسم متاحان عبر شجرة البنية	⁨PDF/UA-2⁩ §8.2.4

الوسم ← الإحالة المرجعية إلى ⁨ISO 32000-2⁩ §14.9

يستخدم المرجع والجسم أنواع البنية القياسية ⁨footnote/endnote⁩ في ⁨PDF 2.0.⁩ المرجع الخلفي المتبادل هو عقدة الحاشية السفلية المتاحة للوصول.

تخطيط ⁨WCAG 2.2⁩

يدعم اقتران مرجع الحاشية السفلية بجسمه معيار النجاح ⁨SC 1.3.1⁩ (المعلومات والعلاقات) ومعيار النجاح ⁨SC 2.4.1⁩ (تجاوز الكتل) من ⁨Web Content Accessibility Guidelines⁩ (⁨WCAG⁩) 2.2 على مستوى المحتوى.

تعني النتيجة الناجحة من أداة إمكانية الوصول إجراء فحص لإمكانية الوصول، وليست شهادة مطابقة؛ ويعود هذا القرار إلى مدقق مستقل.

السياق التجاري

تندرج أداة فحص إمكانية الوصول ضمن فئة ⁨Pro⁩ ولا تُسجَّل إلا عند تثبيت nextpdf/premium إلى جانب الخادم.

تفاصيل ⁨Connect⁩

توفر النقل (⁨MCP⁩ / ⁨REST⁩ / ⁨gRPC⁩)

تُستدعى create_pdf وadd_html وفحص إمكانية الوصول بالطريقة نفسها عبر ⁨Model Context Protocol⁩ (⁨MCP⁩) و⁨REST⁩ و⁨gRPC⁩ من خلال منفّذ الأدوات المشترك.

فئة مخاطر ⁨HITL⁩

يقع إنشاء المستند واستيعاب ⁨HTML⁩ ضمن مستوى التنبيه؛ أما فحص إمكانية الوصول فهو للقراءة فقط. ولا يكون أيٌّ منها approval_required افتراضيًا. راجع /⁨connect/hitl-risk-tiers/.⁩

غلاف ⁨JSON⁩ لبوابة التأكيد

لا تُشغّل هذه الأدوات البوابة ما لم يرفع تجاوزٌ صادر عن المشغّل إحداها إلى approval_required. عقد الغلاف ورمز الاستخدام الواحد موجودان في /⁨connect/hitl-risk-tiers/.⁩

انظر أيضًا

• /⁨cookbook/connect/aria-tagged-pdf/⁩ — تخطيط أدوار المعالم.
• /⁨cookbook/connect/figure-caption/⁩ — بنية ⁨Figure⁩ / ⁨Caption⁩ المتداخلة.
• /⁨connect/tool-catalog/⁩ — حساب مجموعة الأدوات في كل فئة.
• /⁨connect/hitl-risk-tiers/⁩ — نموذج المخاطر والبوابة.