دليل إنشاء PDF موسوم باستخدام Connect

دليل إنشاء ⁨PDF⁩ موسوم باستخدام ⁨Connect⁩

نطاق المطابقة (اقرأ هذا أولًا). ينشئ ⁨NextPDF⁩ البنية الموسومة والنص البديل والبيانات الوصفية التي يتطلبها ⁨PDF/UA-2.⁩ وهذا يجعل المخرجات مُعَدّة للمطابقة مع ⁨PDF/UA-2⁩ (⁨ISO 14289-2⁩)، لكنه لا يجعل المستند “مطابقًا” تلقائيًا. تحدد المطابقة أداة تدقيق مستقلة، وهي ⁨veraPDF⁩ في وضع ⁨PDF/UA-2⁩ الصارم. افهم كل عبارة “⁨PASS⁩” أو “⁨conformant⁩” أو “⁨compliant⁩” واردة أدناه على أنها “المستند مُعَدّ لأن يطابق؛ و⁨veraPDF⁩ هو الذي يحدد النتيجة”.

لمحة سريعة

في هذا الدليل، ستنشئ ملف ⁨Portable Document Format⁩ (⁨PDF⁩) موسومًا عبر وسائل نقل ⁨Connect.⁩ فعّل الوضع الموسوم، وعيّن عنوانًا، وأضف ⁨HTML⁩ دلاليًا، ثم تحقّق من النتيجة باستخدام أداة فحص المعايير وبـ ⁨veraPDF.⁩ أدوات الوضع الموسوم والمحتوى المستخدمة هنا من الفئة الأساسية. أما أداة فحص المعايير فهي من فئة ⁨Pro/Enterprise⁩، ولا تُسجَّل عبر class_exists() إلا عند تثبيت nextpdf/premium إلى جانب الخادم.

التثبيت

composer require nextpdf/server

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

تجعل البنية المنطقية، مع تحديد اللغة الطبيعية، المحتوى قابلًا للتصفح بترتيب القراءة (⁨ISO 32000-2⁩ §14.7). يحتفظ المُدخَل /Alt بوصف بديل للمحتوى غير النصي (⁨ISO 32000-2⁩ §14.8). يجب أن يظهر المحتوى في شجرة البنية، ومدقق المطابقة هو من يقرر النتيجة (⁨PDF/UA-2⁩ §8.2.4). عندما تكتب ⁨HTML⁩ دلاليًا جيد البنية، ينتج خط الأنابيب البنية الصحيحة نيابةً عنك. يعتمد هذا الدليل على ذلك المسار بدلًا من مطالبتك ببناء البنية يدويًا.

واجهة ⁨API⁩

تُطابَق أسماء الأدوات مع السجل قيد التشغيل عبر tools/list. الكتالوج المعتمد هو /⁨connect/tool-catalog/.⁩ ولا يكرر هذا الدليل قائمة الأدوات.

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

إليك أقصر مسار. فعّل الوضع الموسوم مع تحديد لغة، وعيّن عنوانًا، ثم أضف المحتوى.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

فعّل الوضع الموسوم قبل أول استدعاء للمحتوى. يثبّت الكاتب الوضع عند إصدار الصفحة الأولى. إذا فعّلته لاحقًا، فلن يوسم ⁨NextPDF⁩ المحتوى الذي صدر بالفعل بأثر رجعي. عنوان المستند إلزامي في ⁨PDF/UA-2⁩، كما يضبط الوضع الموسوم تفضيل عنوان العارض.

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

أضف ⁨HTML⁩ دلاليًا. يربط خط الأنابيب العناوين والقوائم والجداول ذات <th scope> والروابط والأشكال ذات alt بأنواع البنية الصحيحة:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

بعد ذلك، شغّل فحص المعايير مقابل ⁨PDF/UA-2⁩، وشغّل ⁨veraPDF⁩ --flavour ua2 على المخرجات. نتيجة الفحص وحكم ⁨veraPDF⁩ تقييمان؛ يخبرانك بما إذا كان المستند مُعَدًّا للمطابقة. ⁨veraPDF⁩، وليس ⁨NextPDF⁩، هو الذي يقرر المطابقة.

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

• تفعيل الوضع الموسوم بعد المحتوى. أي محتوى تضيفه قبل تفعيل الوضع يكون غير موسوم. يفيد الفحص بوجود فشل في وسم المحتوى. فعّل الوضع فور إنشاء المستند.
• صورة معلوماتية بدون alt. يفيد الفحص بوجود فشل في النص البديل للشكل. وفّر نصًا بديلًا، أو علّم الصورة الزخرفية بوصفها أثرًا (/⁨cookbook/connect/page-artifacts/⁩).
• تخطّي مستوى عنوان. يُعد تخطّي مستوى، مثل H1 ثم H3، فشلًا في ترتيب العناوين. انتقل إلى مستوى أدنى بمقدار مستوى واحد على الأكثر في كل مرة.
• <th> بدون scope. خلية رأس بلا خلايا بيانات مرتبطة بها هي فشل في بنية الجدول. امنح كل <th> إما scope="col" أو scope="row".
• عنوان مفقود. المستند بلا عنوان هو فشل في البيانات الوصفية. عيّن العنوان بعد تفعيل الوضع الموسوم.

الأداء

الميزانية المعلنة أعلاه حدّ توثيقي. ويمثل الوسم جزءًا من تمريرة التخطيط المعتادة.

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

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

المطابقة

ربط ⁨PDF/UA-2⁩

يرتبط ⁨HTML⁩ الدلالي بأنواع البنية المعيارية في ⁨PDF/UA-2⁩ (H1–H6، P، L/LI/Lbl/LBody، Table/TR/TH/TD، Link، Figure/Caption، Aside). الربط تلقائي. دورك ضمن هذا العقد هو كتابة ⁨HTML⁩ دلالي.

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

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

ربط ⁨WCAG 2.2⁩

تدعم البنية معايير النجاح ⁨WCAG 2.2 SC 1.1.1⁩ و1.3.1 و2.4.1 و2.4.6 على مستوى المحتوى. بصفتك مؤلف المحتوى، تظل مسؤولًا عن قرارات التأليف على مستوى ⁨WCAG.⁩

يُنتج ⁨NextPDF⁩ مخرجات مُعَدّة للمطابقة مع ⁨PDF/UA-2.⁩ وهو لا يؤكد المطابقة. ⁨veraPDF⁩، أو مدقق آخر، هو الذي يقرر المطابقة. الفحص الناجح أو تشغيل ⁨veraPDF⁩ مؤشر على أن المخرجات مُعَدّة للمطابقة، وليس شهادة من ⁨NextPDF.⁩

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

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

خصوصيات ⁨Connect⁩

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

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

فئة مخاطر ⁨HITL⁩

يندرج تفعيل الوضع الموسوم واستخدام أدوات المحتوى ضمن مستوى الحذر. أما فحص المعايير فهو للقراءة فقط. يتطلب مسار إخراج كتابة الملف موافقة، أما وضع ⁨base64⁩ فلا يتطلبها. انظر /⁨connect/hitl-risk-tiers/.⁩

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

عندما يكون مسار إخراج كتابة الملف مُبوَّبًا، تُعيد البوابة غلاف تحدٍّ ورمزًا أحادي الاستخدام. يرتبط الرمز باسم الأداة، وبقيمة ⁨nonce⁩، وبمدة بقاء قدرها 300 ثانية (⁨TTL⁩). للمتابعة، أعد استدعاء الأداة مع arguments._confirmation_token. انظر /⁨connect/hitl-risk-tiers/.⁩

انظر أيضًا

• /⁨cookbook/connect/conformance-mode/⁩ — مُميِّز الوضع الكامن وراء الوضع الموسوم.
• /⁨cookbook/connect/aria-tagged-pdf/⁩ — ربط أدوار المعالم.
• /⁨cookbook/connect/page-artifacts/⁩ — استبعاد المحتوى الزخرفي من شجرة البنية.
• /⁨connect/tool-catalog/⁩ — حصر مجموعة الأدوات لكل فئة.