Zgodność z PDF/UA-2: oznaczona struktura emitowana przez NextPDF dla ISO 14289-2

W skrócie

Granica odpowiedzialności. NextPDF emituje oznaczoną strukturę, która wspiera tworzenie dostępnych treści; nie deklaruje zgodności z PDF/UA-2 — o tym rozstrzyga walidator.

PDF/UA-2 to ISO 14289-2:2024, profil dostępności nałożony na oznaczony Portable Document Format (PDF) 2.0. NextPDF Core emituje drzewo struktury, oznaczoną treść, język katalogu i struktury oraz znacznik pdfuaid za pośrednictwem Document::enableTaggedPdf(). Biblioteka tworzy dostępną strukturę; o zgodności decyduje walidator PDF/UA, taki jak verapdf --flavour ua2. ISO 14289-2 §8.1 definiuje zgodność jako wymagania dotyczące formatu pliku, które dokument musi spełniać i których spełnienie ocenia walidator, a nie jako deklarację składaną przez producenta.

Instalacja

composer require nextpdf/core:^3

Oznaczanie PDF/UA-2 jest funkcją pakietu Core (security.tagged_pdf). Do samej emisji oznaczonej struktury nie jest potrzebny pakiet Premium.

Przegląd koncepcyjny

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) ustawia ConformanceMode::PdfUa2 i podłącza TaggedContentEmitter. Tryb jest jedynym źródłem prawdy o tym, czy dokument jest oznaczony zgodnie ze specyfikacją; warstwa zapisu realizuje następnie obowiązki strukturalne, które nakłada ISO 14289-2:

Rzeczywista treść jest oznaczona — §8.2.2: każdy fragment rzeczywistej treści niebędącej artefaktem trafia do struktury logicznej, a artefakty są oznaczane jako artefakty. Opiera się to na strukturze oznaczonego PDF z ISO 32000-2 §14.7 (StructTreeRoot, elementy struktury, identyfikatory MCID).
Język naturalny jest zadeklarowany — §8.4.4: dokument oraz zmiany języka mają atrybut Lang. Przy ConformancePolicy::strictUa2() nieprawidłowy tag BCP 47 jest odrzucany na granicy API, w trybie fail-fast, zamiast być po cichu pomijanym podczas zapisu.
Ilustracje mają opisy alternatywne — §8.5.1: każdy element struktury Figure ma opis alternatywny.
Tabele wiążą nagłówki z danymi — §8.2.5.26: powiązanie komórek header/data w tabeli jest wyrażone strukturalnie.

NextPDF emituje te struktury. Nie przeprowadza oceny zgodności z §8.1; to rola walidatora i norma zastrzega ją właśnie dla niego.

Powierzchnia API

Metoda	Efekt
`enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static`	Ustawia `ConformanceMode::PdfUa2`, podłącza `TaggedContentEmitter` i waliduje `$lang` zgodnie z polityką. Zgłasza `InvalidConfigException`, gdy polityka wymaga walidacji Lang, a `$lang` jest nieprawidłowy.
`beginTag()/endTag()`	Ręczna struktura dla treści innych niż HTML; typy kontenerowe stają się elementami grupującymi, a typy liściowe otrzymują identyfikatory MCID.
`ConformanceMode::requiresPdfUa2PageTabs(): bool`	Wartość true dla `PdfUa2` — wymusza ustawienie strony `/Tabs /S`.

Przykład kodu — szybki start

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Conformance\ConformancePolicy;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/accessible.pdf';

$doc = Document::createStandalone();
$doc->enableTaggedPdf('en', ConformancePolicy::strictUa2()); // fail-fast Lang
$doc->setTitle('Accessible report 2026');
$doc->writeHtml('<h1>Quarterly report</h1><p>Body text.</p>'
    . '<img src="chart.png" alt="Revenue rose 12% quarter on quarter">');
$doc->save($out);

echo "Wrote {$out} — validate: verapdf --flavour ua2 {$out}\n";

Przykład kodu — środowisko produkcyjne

Bramka produkcyjna uruchamia verapdf --flavour ua2 out.pdf i przerywa kompilację, gdy walidator zgłosi naruszenia. Test integracyjny tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php sprawdza, czy referencyjna próbka HTML→oznaczony PDF przechodzi walidację veraPDF UA-2 (pomijany, gdy veraPDF jest niedostępny). Werdykt walidatora stanowi bramkę, a wynik emitera jest jej danymi wejściowymi.

Przypadki brzegowe i pułapki

Włącz najpierw. enableTaggedPdf() wywołane po writeHtml() nie oznacza wstecznie już zapisanej treści.
Ścisły tryb językowy. Przekaż ConformancePolicy::strictUa2(), aby odrzucić nieprawidłowy tag BCP 47 na granicy API, zamiast otrzymać błąd dopiero przy późniejszej walidacji veraPDF.
Ponowne włączenie jest idempotentne. Dwukrotne wywołanie aktualizuje język bez przebudowywania wypełnionego drzewa struktury.
Pusty oznaczony dokument. Pusty oznaczony dokument nie deklaruje PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): znacznik nie jest emitowany dla dokumentu bez rzeczywistej treści, dzięki czemu plik nie składa nadmiarowej deklaracji.

Wydajność

Emisja drzewa struktury jest proporcjonalna do liczby elementów. Budżet dla typowego raportu to czas rzeczywisty ≤ 1500 ms i szczytowe zużycie pamięci ≤ 64 MB.

Uwagi dotyczące bezpieczeństwa

Oznaczanie dostępności ma charakter strukturalny; nie jest mechanizmem zabezpieczeń. Z założenia udostępnia logiczną strukturę dokumentu technologiom wspomagającym. Drzewo znaczników nie zapewnia poufności.

Odwzorowanie PDF/UA-2

Obowiązek PDF/UA-2	Klauzula ISO 14289-2	Emisja NextPDF
Rzeczywista treść oznaczona w strukturze logicznej	§8.2.2	`TaggedContentEmitter` + `StructureTree`
Zadeklarowany język dokumentu/struktury	§8.4.4	`/Lang` w katalogu, walidowany przez `Bcp47Validator`
Opis alternatywny ilustracji	§8.5.1	`alt` → `/Alt` w elemencie Figure
Powiązanie header/data w tabeli	§8.2.5.26	Struktura TR/TH/TD z tabel HTML

Odniesienia: znacznik → ISO 32000-2 §14.9

PDF/UA-2 nakłada się na model oznaczonego PDF z ISO 32000-2. Elementy struktury emitowane przez NextPDF odwzorowują się na strukturę logiczną z ISO 32000-2 §14.7 (StructTreeRoot, elementy struktury, identyfikatory MCID) — chunk — oraz na standardową przestrzeń nazw struktury zdefiniowaną dla PDF 2.0. Mapa ról wiąże elementy HTML (h1, p, table) ze standardowymi typami struktury, aby walidator UA-2 mógł je rozpoznać.

Odwzorowanie WCAG 2.2

Oznaczona struktura stanowi techniczną podstawę kryteriów sukcesu Web Content Accessibility Guidelines (WCAG) 2.2 — 1.1.1 (alternatywy nietekstowe, poprzez /Alt elementu Figure z §8.5.1), 1.3.1 (informacje i relacje, poprzez drzewo struktury) oraz 1.3.2 (zrozumiała kolejność, poprzez kolejność odczytu). Emisja struktury jest konieczna, ale nie wystarcza do zgodności z WCAG; o tym rozstrzyga audyt dostępności, a nie biblioteka.

Zachowanie w trybie FIPS

Emisja PDF/UA-2 nie wykonuje żadnych operacji kryptograficznych. Tryb Federal Information Processing Standards (FIPS) nie ma wpływu na ścieżkę oznaczonej struktury.

Zgodność

Deklaracja	Specyfikacja	Klauzula
Wersja PDF/UA jest identyfikowana przez przestrzeń nazw schematu `pdfuaid` (Tabela 1).	ISO 14289-2	§5
Zgodność z PDF/UA-2 nakłada wymagania dotyczące formatu pliku, które dokument musi spełniać (zgodność ocenia walidator; producent jej nie deklaruje).	ISO 14289-2	§8.1
Rzeczywista treść musi być oznaczona w strukturze logicznej.	ISO 14289-2	§8.2.2
Język naturalny dokumentu musi być zadeklarowany.	ISO 14289-2	§8.4.4
Elementy Figure wymagają opisu alternatywnego.	ISO 14289-2	§8.5.1
Struktura tabeli musi wiązać komórki nagłówkowe z komórkami danych.	ISO 14289-2	§8.2.5.26
Dostępna struktura opiera się na strukturze logicznej oznaczonego PDF z ISO 32000-2.	ISO 32000-2	§14.7.2

Cytowania są wskaźnikami w postaci identyfikatora klauzuli oraz reference_id, odsyłającymi do korpusu weryfikacyjnego. Tekst norm nie jest powielany.