إنشاء ملف PDF موسوم لإمكانية الوصول من HTML

لمحة سريعة

استخدم هذه الوصفة لإنشاء ملف ⁨PDF⁩ موسوم من ⁨HTML⁩ دلالي. ينشئ ⁨NextPDF⁩ شجرة البنية المنطقية، ويضبط لغة الفهرس، ويضيف علامات ⁨PDF/UA-2.⁩ وتبقى أداة الفحص هي المرجع في تحديد المطابقة. تتبع هذه الوصفة examples/31-pdfua2-tagged.php.

المتطلبات الأساسية

ثبّت ⁨Core⁩: composer require nextpdf/core:^3.
استخدم أداة تحقق ⁨PDF/UA⁩ للتحقق من الصحة. يستخدم المثال ⁨veraPDF.⁩

الوصفة

أنشئ المستند.
استدعِ enableTaggedPdf() مع وسم لغة وفق ⁨Best Current Practice⁩ (⁨BCP⁩) 47 قبل writeHtml(). يرصد مسار معالجة ⁨HTML⁩ الوضع الموسوم عند بناء المحلّل، ثم يربط باعث المحتوى الموسوم.
عيّن بيانات المستند الوصفية (العنوان، اللغة). يمكنك استدعاء setLanguage() بأمان مع enableTaggedPdf() لأن ذلك عديم التأثير عند التكرار.
اكتب ⁨HTML⁩ دلاليًا. يربط المحلّل كل عنصر كتلي بعنصر بنية: h1 إلى H1، وp إلى P، وul/li إلى L/LI، وtable إلى Table/TR/TD.
احفظ، ثم تحقق من الصحة باستخدام أداة فحص ⁨PDF/UA.⁩

مثال كامل

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Step 2 — enable tagged mode BEFORE writeHtml(). The lang argument
// drives the catalog /Lang entry and the structure tree root language.
$doc->enableTaggedPdf(lang: 'en');

// Step 3 — metadata. setLanguage() restates intent; it is idempotent here.
$doc->setTitle('Accessible Report');
$doc->setLanguage('en');

$doc->addPage();

// Step 4 — semantic HTML. Each block element becomes a StructElem; text
// runs are wrapped in BDC/EMC operators with stable MCIDs.
$html = <<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<h2>Findings</h2>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML;

$doc->writeHtml($html);

$doc->save(__DIR__ . '/accessible.pdf');

echo "Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf\n";

المخرجات المتوقعة

Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf

يتضمن الناتج شجرة بنية، و/MarkInfo << /Marked true >>، ومدخل الفهرس /Lang، وعلامة ⁨XMP⁩ المسماة pdfuaid:part. شغّل أداة الفحص للتأكد من وجود هذه العناصر واتساقها داخليًا.

الحالات الحدية

ترتيب الاستدعاء. استدعاء enableTaggedPdf() بعد writeHtml() لا يوسم المحتوى المكتوب سابقًا بأثر رجعي. فعّل الوضع الموسوم أولًا.
وسم اللغة. مرّر ConformancePolicy::strictUa2() كوسيط ثانٍ لرفض وسم ⁨BCP-47⁩ المشوَّه عند حدود واجهة ⁨API⁩ بدلًا من إسقاطه بصمت أثناء الكتابة.
إعادة التفعيل عديمة التأثير عند التكرار. إذا استدعيت enableTaggedPdf() مرتين، يحدّث ⁨NextPDF⁩ اللغة دون إعادة بناء شجرة البنية التي سبق أن ملأتها.
الوسم اليدوي. بالنسبة للمحتوى غير ⁨HTML⁩، غلّف العناصر بـ beginTag() / endTag(). تصبح أنواع الحاويات (Table، THead، TBody، TFoot، TR، L، LI، وعناصر التجميع Sect/Div/Art/Aside/BlockQuote) عناصر تجميع دون محتوى موسوم؛ ويُغلَّف المحتوى السطري الطليق الموضوع مباشرةً داخل عنصر تجميع في P مُركَّب. تحصل الأنواع الطرفية (P، H1–H6، TD، TH) على معرّفات ⁨MCID.⁩
الدعم لا يعني المطابقة. يُصدر ⁨NextPDF⁩ البيانات الوصفية البنيوية التي يحتاجها ⁨PDF/UA-2.⁩ ويُظهر أيضًا تحذيرًا عن تدهور التكافؤ: للاعتماد الإنتاجي، يتحمل المستدعي مسؤولية التحقق خارجيًا عبر مرجع موثوق. شغّل أداة فحص قبل أن تعلن أن ملفًا مطابقًا.
جداول ⁨HTML⁩ الموسومة وعناصر التجميع تجتاز ⁨veraPDF ua2⁩. يُصدِر جدول ⁨<table>⁩ موسوم — مسطّح، أو بـ colspan/rowspan، أو مُقسَّم على عدة صفحات، أو متداخل داخل خلية — بنية Table/TR/TH/TD (⁨ISO 32000-2⁩ §⁨14.8⁩؛ تحمل الخلايا الممتدة سمتَي /ColSpan و/RowSpan من ⁨Table 384⁩)، وتُصدِر عناصر التجميع <section>/<div>/<article>/<aside>/<blockquote> بنية تجميع مع تغليف المحتوى السطري الطليق في P مُركَّب. يبلّغ ⁨veraPDF⁩ ‏--flavour ua2 عن صفر إخفاقات في هذه الحالات. تبقى حالة واحدة تُخفِق: عنصر كتلي متداخل داخل عنصر سطري — عنوان داخل رابط، <a><h2>…</h2></a> — يستدعي Link shall not contain Hn، فأبقِ المحتوى الكتلي خارج الأغلفة السطرية. شغّل أداة فحص قبل أن تعلن أن ملفًا مطابقًا.

المطابقة

العبارة	المواصفة	البند
يستلزم المحتوى الفعلي بنية منطقية.	⁨ISO 14289-2⁩	§8.2.2
تلتزم عناصر البنية بتداخل وترتيب قراءة محدَّدين.	⁨ISO 14289-2⁩	§8.2.3

توضح هذه الوصفة كيفية إنتاج البنية الموسومة التي تدعم التأليف المراعي لإمكانية الوصول. ولا تؤكد مطابقة ⁨PDF/UA-2⁩؛ فأداة الفحص هي التي تحدد ذلك.