Tworzenie oznakowanego pliku PDF z kodu HTML na potrzeby dostępności

W skrócie

Ten przepis pokazuje, jak utworzyć oznakowany plik PDF z semantycznego kodu HTML. NextPDF zapisuje drzewo struktury logicznej, język katalogu oraz znaczniki PDF/UA-2. O zgodności rozstrzyga walidator. Przepis opiera się na examples/31-pdfua2-tagged.php.

Wymagania wstępne

Zainstaluj Core: composer require nextpdf/core:^3.
Do weryfikacji użyj walidatora PDF/UA; w przykładzie wykorzystano veraPDF.

Przepis

Utwórz dokument.
Wywołaj enableTaggedPdf() ze znacznikiem języka zgodnym z Best Current Practice (BCP) 47 przed writeHtml(). Potok HTML wykrywa tryb oznakowany podczas budowania parsera, a następnie podłącza generator oznakowanej treści.
Ustaw metadane dokumentu (tytuł, język). setLanguage() można bezpiecznie wywołać razem z enableTaggedPdf(), ponieważ jest to operacja idempotentna.
Zapisz semantyczny kod HTML. Parser mapuje każdy element blokowy na element struktury: h1 na H1, p na P, ul/li na L/LI, a table na Table/TR/TD.
Zapisz plik, a następnie sprawdź poprawność walidatorem PDF/UA.

Pełny przykład

<?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";

Oczekiwany wynik

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

Wynik zawiera drzewo struktury, /MarkInfo << /Marked true >>, wpis /Lang w katalogu oraz znacznik XMP pdfuaid:part. Uruchom walidator, aby potwierdzić obecność tych elementów i ich spójność wewnętrzną.

Przypadki brzegowe

Kolejność wywołań. Wywołanie enableTaggedPdf() po writeHtml() nie oznakowuje wstecznie treści, która została już zapisana. Najpierw włącz tryb oznakowany.
Znacznik języka. Przekaż ConformancePolicy::strictUa2() jako drugi argument, aby odrzucić nieprawidłowy znacznik BCP 47 już na granicy API, zamiast po cichu pomijać go podczas zapisu.
Idempotentne ponowne włączenie. Jeśli wywołasz enableTaggedPdf() dwukrotnie, NextPDF zaktualizuje język bez przebudowywania już wypełnionego drzewa struktury.
Ręczne oznakowanie. W przypadku treści innych niż HTML opakuj elementy w beginTag() / endTag(). Typy kontenerowe (Table, TR, L, LI) stają się elementami grupującymi bez oznakowanej treści. Typy liściowe (P, H1–H6, TD) otrzymują identyfikatory MCID.
Obsługa nie oznacza zgodności. NextPDF generuje metadane strukturalne wymagane przez PDF/UA-2. Zgłasza także ostrzeżenie o obniżonej zgodności: przy zatwierdzaniu produkcyjnym to strona wywołująca odpowiada za walidację przez zewnętrzną wyrocznię. Uruchom walidator, zanim stwierdzisz, że plik jest zgodny.

Zgodność

Stwierdzenie	Specyfikacja	Punkt	reference_id
Rzeczywista treść wymaga struktury logicznej.	ISO 14289-2	§8.2.2
Elementy struktury przestrzegają zdefiniowanego zagnieżdżenia i kolejności odczytu.	ISO 14289-2	§8.2.3

Ten przepis pokazuje, jak utworzyć oznakowaną strukturę wspierającą tworzenie dostępnych treści. Nie potwierdza zgodności z PDF/UA-2; o tym rozstrzyga walidator.