ربط أدوار معالم ARIA بملف PDF موسوم عبر Connect

ربط أدوار معالم ⁨ARIA⁩ بملف ⁨PDF⁩ موسوم عبر ⁨Connect⁩

نظرة سريعة

أرسِل ⁨HTML⁩ يستخدم عناصر التقسيم في ⁨HTML5⁩ وأدوار المعالم في تطبيقات الإنترنت الغنية الميسَّرة (⁨ARIA⁩) عبر ⁨Connect.⁩ يربطها خط معالجة المحتوى الموسوم بأنواع البنية المعيارية في ⁨PDF 2.0⁩، ما يتيح للتقنيات المساعِدة التنقل حسب المعالم بدلاً من الموضع المرئي. أداة فحص إمكانية الوصول المستخدمة هنا من فئة ⁨Pro⁩: تُكتشَف الأداة عبر فحص class_exists() ولا تُسجَّل إلا عند تثبيت nextpdf/premium إلى جانب الخادم. أما إنشاء المستند واستيعاب ⁨HTML⁩ فيستخدمان أدوات النواة.

تُبلِّغ أداة إمكانية الوصول عن النتائج وفق ⁨PDF/UA-2⁩ (⁨ISO 14289-2⁩). تعني النتيجة الناجحة اجتياز تقييم الأداة نفسها. هذا فحص لإمكانية الوصول، وليس شهادة مطابقة مستقلة. وتُحدَّد المطابقة بواسطة أداة ⁨veraPDF⁩ أو مدقِّق آخر.

التثبيت

composer require nextpdf/server

تأكَّد من وجود أداة إمكانية الوصول في إصدار ⁨Pro⁩ ضمن بيئة النشر العاملة عبر استدعاء tools/list (انظر /⁨connect/tool-catalog/⁩). إذا لم تكن موجودة، فهذا يعني أن nextpdf/premium غير مثبَّت على هذا النشر، ولذلك يتعذَّر تشغيل خطوة التحقق في هذه الوصفة.

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

تنظِّم عناصر بنية التجميع البنية المنطقية للمستند في أقسام وحاويات مماثلة (⁨ISO 32000-2⁩ §14.8). يربط خط معالجة ⁨HTML⁩ هذه العناصر:

• <aside> وrole="complementary" → النوع المعياري Aside في ⁨PDF 2.0⁩
• <article> / role="article" → Art
• <nav> / role="navigation" → Sect

لا يُقبل نوع البنية غير المعياري إلا عند ربط دوره بنوع معياري (⁨PDF/UA-2⁩ §8.2.5). يُصدِر خط المعالجة النوع المعياري مباشرة، لذلك لا تحتاج إلى خريطة أدوار يدوية. يجب أن يُمثَّل المحتوى في شجرة البنية حتى تتمكن التقنيات المساعِدة من الوصول إليه (⁨PDF/UA-2⁩ §8.2.4).

سطح ⁨API⁩

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

عينة شيفرة — بداية سريعة

أنشئ مستند ⁨PDF 2.0⁩ موسومًا، وأضِف ⁨HTML⁩ بأدوار المعالم، ثم افحصه عبر تسلسل طلبات tools/call في ⁨MCP⁩:

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

اربط مُصدِر المحتوى الموسوم قبل إضافة أي ⁨HTML.⁩ أنشئ المستند مع ضبط لغة محدَّدة، حتى يكون المُصدِر نشطًا منذ أول استدعاء للمحتوى.

عينة شيفرة — الإنتاج

أضِف ⁨HTML⁩ الذي يتضمن المعالم وشغِّل فحص إمكانية الوصول. تعامَل مع الحالة غير الناجحة كنتيجة عادية للفحص، لا كخطأ في النقل:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

يتضمن ردّ الفحص شجرة البنية التي رصدها وملخص نتائج ⁨PDF/UA-2.⁩ ويُمثَّل كلٌّ من <aside> و<div role="complementary"> بالنوع المعياري نفسه، Aside.

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

• الإصدار الموسوم غير نشط قبل المحتوى. إذا لم يُنشأ المستند مع لغة / وضع موسوم، فإن أول إضافة ⁨HTML⁩ تُنتج محتوى غير موسوم، ويُبلِّغ الفحص عن فشل في المحتوى الموسوم. أعِد إنشاء المستند مع ضبط اللغة.
• دور متعارض على عنصر تقسيم (<aside role="navigation">) يُنتج تحذيرًا. أزِل الدور المتعارض أو استخدِم <div>.
• الأداة غائبة. بدون nextpdf/premium، لا تُسجَّل أداة إمكانية الوصول في إصدار ⁨Pro⁩، وتفشل خطوة التحقق بخطأ أداة غير معروفة.

الأداء

الميزانية الواردة في ⁨frontmatter⁩ هي حدّ توثيقي. ربط المعالم جزء من مسار التخطيط العادي، ولا يضيف مرحلة منفصلة قابلة للقياس في المستندات المعتادة.

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

لا توجد إرشادات إضافية بخلاف قاعدة النقل العامة في ⁨Connect⁩: لا تُسجِّل محتوى المستند أو جسم ⁨HTML⁩ عند مستوى تسجيل يُصدَّر خارجيًا.

المطابقة

ربط ⁨PDF/UA-2⁩

⁨HTML⁩	النوع المعياري في ⁨PDF 2.0⁩
<aside>، role="complementary"	Aside
<article>، role="article"	Art
<nav>، role="navigation"	Sect

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

الادّعاء	البند	⁨reference_id⁩
تنظِّم عناصر التجميع البنية المنطقية في أقسام	⁨ISO 32000-2⁩ §14.8
تتطلب الأنواع غير المعيارية ربط الدور بنوع معياري	⁨PDF/UA-2⁩ §8.2.5
يجب أن يكون المحتوى قابلاً للوصول عبر شجرة البنية	⁨PDF/UA-2⁩ §8.2.4

ربط ⁨WCAG 2.2⁩

يدعم التنقل بالمعالم معيار النجاح ⁨SC 1.3.1⁩ (⁨Info and Relationships⁩) و ⁨SC 2.4.1⁩ (⁨Bypass Blocks⁩) في ⁨WCAG 2.2⁩ على مستوى المحتوى. تحمل صيغة ⁨PDF⁩ هذه البنية. يظل مؤلف المحتوى مسؤولاً عن قرارات التأليف على مستوى ⁨WCAG.⁩

تعني النتيجة الناجحة لأداة إمكانية الوصول اجتياز فحص إمكانية الوصول، وليست شهادة مطابقة. يحدِّد مدقِّق مستقل (مثل ⁨veraPDF⁩) مطابقة ⁨PDF/UA-2.⁩

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

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

تفاصيل ⁨Connect⁩

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

استدعِ create_pdf وadd_html وفحص إمكانية الوصول بالطريقة نفسها عبر tools/call في ⁨MCP⁩، ونقطة طرف أداة ⁨REST⁩، وخدمة ⁨gRPC⁩، من خلال منفِّذ الأدوات المشترك.

فئة المخاطر في ⁨HITL⁩

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

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

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

انظر أيضًا

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