إصدار عنصر Figure قابل للوصول مع Caption عبر Connect

إصدار عنصر ⁨Figure⁩ قابل للوصول مع ⁨Caption⁩ عبر ⁨Connect⁩

لمحة سريعة

أرسِل عبر نواقل ⁨Connect⁩ عنصر <figure> من ⁨HTML⁩ يحتوي على <img> و <figcaption>. يُصدِر المسار عنصر بنية قياسيًا من نوع Figure، ويُضمِّن التسمية التوضيحية بصفتها عنصرًا فرعيًا من نوع Caption، ويستخدم سمة alt لملء /Alt. تحقّق من النتيجة باستخدام أداة الوصول من فئة ⁨Pro⁩. يكتشف ⁨NextPDF⁩ تلك الأداة عبر class_exists() ولا يسجّلها إلا عند تثبيت nextpdf/premium إلى جانب الخادم. تتولّى الأدوات الأساسية إنشاء المستند واستيعاب ⁨HTML⁩.

تعني نتيجة أداة الوصول الناجحة اجتياز فحص الوصول، لا الحصول على شهادة مطابقة مستقلة.

التثبيت

composer require nextpdf/server

تأكّد من توافر أداة الوصول من فئة ⁨Pro⁩ باستدعاء tools/list. راجِع /⁨connect/tool-catalog/.⁩

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

يوفّر الوصف البديل نصًا للمحتوى غير النصّي، مثل عنصر ⁨figure⁩ (⁨ISO 32000-2⁩ §14.8). يخزّن عنصر البنية هذا الوصف في مدخل /Alt الخاص به (⁨ISO 32000-2⁩ §14.8). تملأ سمة alt في ⁨HTML⁩ قيمة /Alt في عنصر Figure المُصدَر. يُصدِر المسار عنصر <figcaption> بصفته عنصرًا فرعيًا مُضمَّنًا من نوع Caption، لا فقرة شقيقة، كي تبقى التسمية التوضيحية قابلة للوصول كجزء من عنصر ⁨figure⁩ (⁨PDF/UA-2⁩ §8.2.4).

واجهة ⁨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": "Architecture Reference", "language": "en" }
  }
}

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

أضِف ترميز عنصر ⁨figure⁩. سمة alt مطلوبة ليكون عنصر ⁨figure⁩ قابلًا للوصول:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

شغّل فحص الوصول، ثم افحص شجرة البنية المُبلَّغ عنها. ينبغي أن تُظهر عنصر Figure واحدًا يحتوي على /Alt وعنصرًا فرعيًا واحدًا بالضبط من نوع Caption.

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

• عنصر <img> دون alt. يُبلِّغ الفحص عن إخفاق في النص البديل لعنصر ⁨figure⁩. وفّر قيمة alt وصفية، أو علِّم الصورة الزخرفية الخالصة بصفتها أثرًا (راجِع /⁨cookbook/connect/page-artifacts/⁩).
• عنصر <figcaption> فارغ. يُصدِر المسار تحذيرًا. وفّر نص التسمية التوضيحية أو أزِل العنصر.
• عنصر <figcaption> خارج أيّ <figure>. يُصدِره المسار بصفته تسمية توضيحية يتيمة. غلّفه داخل <figure>.
• الأداة غائبة. عند غياب nextpdf/premium، لا تُسجَّل أداة الوصول من فئة ⁨Pro⁩، ويُخفق التحقّق بخطأ أداة غير معروفة.

الأداء

تمثّل ميزانية المقدّمة (⁨front-matter⁩) حدًا توثيقيًا أعلى. تُنفَّذ معالجة عنصر ⁨figure⁩ ضمن تمريرة التخطيط العادية.

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

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

المطابقة

تعيين ⁨PDF/UA-2⁩

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

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

Figure و Caption نوعا بنية قياسيان. يحدّد تضمين <figcaption> بصفته Caption عقدة عنصر ⁨figure⁩ القابلة للوصول.

تعيين ⁨WCAG 2.2⁩

يدعم عنصر ⁨figure⁩ المزوّد بنص بديل وتسمية توضيحية مرتبطة معياري النجاح ⁨SC 1.1.1⁩ (المحتوى غير النصّي) و⁨SC 1.3.1⁩ (المعلومات والعلاقات) من إرشادات الوصول إلى محتوى الويب (⁨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/aria-noteref-pattern/⁩ — مرجع الحاشية وأدوار المتن.
• /⁨cookbook/connect/page-artifacts/⁩ — تعليم الصور الزخرفية بصفتها آثارًا.
• /⁨connect/tool-catalog/⁩ — حساب مجموعة الأدوات لكلّ فئة.