Mapowanie ról punktów orientacyjnych ARIA na tagowany PDF w Connect

W skrócie

Przetwórz w Connect kod HTML wykorzystujący elementy sekcjonujące HTML5 oraz role punktów orientacyjnych Accessible Rich Internet Applications (ARIA). Potok tagowanej treści mapuje je na standardowe typy struktur PDF 2.0, dzięki czemu technologie wspomagające mogą nawigować według punktów orientacyjnych zamiast według położenia wizualnego. Używana tutaj kontrola ułatwień dostępu należy do wersji Pro: narzędzie jest wykrywane przez sondę class_exists() i rejestruje się tylko wtedy, gdy obok serwera zainstalowany jest pakiet nextpdf/premium. Do tworzenia dokumentu i wczytywania kodu HTML służą narzędzia podstawowe.

Narzędzie ułatwień dostępu zgłasza wyniki w odniesieniu do PDF/UA-2 (ISO 14289-2). Pozytywny wynik jest oceną samego narzędzia. Jest to kontrola ułatwień dostępu, a nie niezależna certyfikacja zgodności. Zgodność ustala veraPDF lub inne narzędzie sprawdzające.

Instalacja

composer require nextpdf/server

Potwierdź wywołaniem tools/list, że narzędzie ułatwień dostępu w wersji Pro jest obecne w działającym wdrożeniu (zobacz /connect/tool-catalog/). Jeśli go brakuje, pakiet nextpdf/premium nie jest zainstalowany w tym wdrożeniu, więc nie można wykonać kroku weryfikacji z tego przepisu.

Przegląd koncepcyjny

Elementy struktury grupującej organizują logiczną strukturę dokumentu w sekcje i podobne kontenery (ISO 32000-2 §14.8). Potok HTML mapuje następujące elementy:

<aside> oraz role="complementary" → standardowy typ Aside w PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Niestandardowy typ struktury jest dopuszczalny tylko wtedy, gdy ma mapowanie roli na typ standardowy (PDF/UA-2 §8.2.5). Potok emituje typ standardowy bezpośrednio, więc ręczne mapowanie ról nie jest potrzebne. Treść musi być odzwierciedlona w drzewie struktury, aby technologie wspomagające mogły uzyskać do niej dostęp (PDF/UA-2 §8.2.4).

Powierzchnia API

Sprawdź nazwy narzędzi w działającym rejestrze za pomocą tools/list. Katalogiem referencyjnym jest /connect/tool-catalog/. Ten przepis korzysta z podstawowych narzędzi tworzenia dokumentu i wczytywania kodu HTML oraz z kontroli ułatwień dostępu w wersji Pro. Nie wskazuje stałej liczby narzędzi.

Przykład kodu — szybki start

Utwórz tagowany dokument PDF 2.0, dodaj kod HTML z rolami punktów orientacyjnych i sprawdź go, wykonując po kolei żądania MCP tools/call:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

Podłącz emiter tagowanej treści, zanim dodasz jakikolwiek kod HTML. Utwórz dokument z ustawionym językiem, aby emiter był aktywny już od pierwszego wywołania dodającego treść.

Przykład kodu — wersja produkcyjna

Dodaj kod HTML z punktami orientacyjnymi i uruchom kontrolę ułatwień dostępu. Status inny niż powodzenie traktuj jako zwykły wynik wymagający zbadania, a nie jako błąd transportu:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

Odpowiedź kontroli zawiera zaobserwowane drzewo struktury oraz podsumowanie wyników względem PDF/UA-2. Zarówno <aside>, jak i <div role="complementary"> sprowadzają się do tego samego standardowego typu Aside.

Przypadki brzegowe i pułapki

Emisja tagów nieaktywna przed dodaniem treści. Jeśli dokument nie został utworzony z ustawionym językiem / trybem tagowanym, pierwsze dodanie kodu HTML wytwarza nietagowaną treść, a kontrola zgłasza niepowodzenie dotyczące tagowanej treści. Utwórz dokument ponownie z ustawionym językiem.
Sprzeczna rola na elemencie sekcjonującym (<aside role="navigation">) generuje ostrzeżenie. Usuń sprzeczną rolę lub użyj elementu <div>.
Brak narzędzia. Bez pakietu nextpdf/premium narzędzie ułatwień dostępu w wersji Pro nie jest zarejestrowane, a krok weryfikacji kończy się błędem nieznanego narzędzia.

Wydajność

Budżet określony we frontmatterze to limit dokumentacyjny. Mapowanie punktów orientacyjnych jest częścią normalnego przebiegu układu. W przypadku typowych dokumentów nie dodaje osobnej, mierzalnej fazy.

Uwagi dotyczące bezpieczeństwa

Poza ogólną regułą transportu Connect nie obowiązują żadne dodatkowe wytyczne: nie zapisuj treści dokumentu ani treści HTML w logach udostępnianych na zewnątrz.

Zgodność

Mapowanie PDF/UA-2

HTML	Standardowy typ PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

Tag → odsyłacz do ISO 32000-2 §14.9

Twierdzenie	Punkt	reference_id
Elementy grupujące organizują logiczną strukturę w sekcje	ISO 32000-2 §14.8
Typy niestandardowe wymagają mapowania roli na typ standardowy	PDF/UA-2 §8.2.5
Treść musi być dostępna przez drzewo struktury	PDF/UA-2 §8.2.4

Mapowanie WCAG 2.2

Nawigacja po punktach orientacyjnych wspiera kryteria sukcesu WCAG 2.2 SC 1.3.1 (Informacje i relacje) oraz SC 2.4.1 (Możliwość pominięcia bloków) na poziomie treści. Format PDF zachowuje strukturę. Za decyzje redakcyjne na poziomie WCAG nadal odpowiada autor treści.

Pozytywny wynik narzędzia ułatwień dostępu to kontrola ułatwień dostępu, a nie certyfikacja zgodności. Zgodność z PDF/UA-2 ustala niezależne narzędzie sprawdzające (na przykład veraPDF).

Kontekst komercyjny

Narzędzie kontroli ułatwień dostępu jest częścią wersji Pro i rejestruje się tylko wtedy, gdy obok serwera zainstalowany jest pakiet nextpdf/premium.

Szczegóły Connect

Dostępność transportu (MCP / REST / gRPC)

Wywołuj create_pdf, add_html oraz kontrolę ułatwień dostępu w ten sam sposób przez MCP tools/call, punkt końcowy narzędzia REST oraz usługę gRPC, korzystając ze współdzielonego wykonawcy narzędzi.

Poziom ryzyka HITL

Tworzenie dokumentu i wczytywanie kodu HTML mają poziom ostrożności (automatyczne wykonanie, rejestrowane w dzienniku audytu). Kontrola ułatwień dostępu jest tylko do odczytu. Domyślnie żadne z tych narzędzi nie jest oznaczone jako approval_required. Zobacz /connect/hitl-risk-tiers/.

Koperta JSON bramki potwierdzenia

Te narzędzia nie uruchamiają bramki, chyba że nadpisanie konfiguracji przez operatora podniesie jedno z nich do poziomu approval_required. Gdy bramka jest aktywna, koperta wyzwania i kontrakt tokenu jednorazowego są zgodne z /connect/hitl-risk-tiers/.

Zobacz także

/cookbook/connect/figure-caption/ — zagnieżdżona struktura Figure / Caption.
/cookbook/connect/aria-noteref-pattern/ — role odsyłacza do przypisu oraz jego treści.
/connect/tool-catalog/ — określanie zestawu narzędzi dla poszczególnych poziomów.
/connect/hitl-risk-tiers/ — model ryzyka i bramka.