Samouczek tworzenia otagowanego pliku PDF przez Connect

Samouczek tworzenia otagowanego pliku PDF przez Connect

Granica zgodności (przeczytaj to najpierw). NextPDF emituje otagowaną strukturę, tekst alternatywny i metadane oczekiwane przez PDF/UA-2. Dzięki temu wynik jest przeznaczony do zgodności z PDF/UA-2 (ISO 14289-2). Samo w sobie nie czyni to dokumentu „zgodnym”. O zgodności decyduje niezależny weryfikator, veraPDF w trybie ścisłym PDF/UA-2. Każde poniższe stwierdzenie „PASS”, „zgodny” lub „spełniający wymogi” rozum jako „dokument jest przeznaczony do zgodności; o wyniku rozstrzyga veraPDF”.

W skrócie

W tym samouczku utworzysz otagowany plik Portable Document Format (PDF) za pośrednictwem transportów Connect. Włączysz tryb otagowany, ustawisz tytuł, dodasz semantyczny HTML i zweryfikujesz wynik za pomocą standards-check oraz veraPDF. Narzędzia trybu otagowanego i narzędzia treści używane tutaj należą do edycji core. Narzędzie weryfikacyjne standards-check należy do poziomu Pro/Enterprise. Jest rejestrowane przez class_exists() tylko wtedy, gdy obok serwera zainstalowany jest nextpdf/premium.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Struktura logiczna wraz z określeniem języka naturalnego umożliwia przeglądanie treści w kolejności czytania (ISO 32000-2 §14.7). Wpis /Alt przechowuje opis alternatywny treści nietekstowej (ISO 32000-2 §14.8). Treść musi być odwzorowana w drzewie struktury, a o zgodności rozstrzyga weryfikator (PDF/UA-2 §8.2.4). Gdy przygotujesz dobrze ustrukturyzowany, semantyczny HTML, potok utworzy poprawną strukturę za Ciebie. Ten samouczek opiera się na tym przepływie i nie wymaga ręcznego budowania struktury.

Powierzchnia API

Nazwy narzędzi są sprawdzane względem aktywnego rejestru za pomocą tools/list. Obowiązującym katalogiem jest /connect/tool-catalog/. Ten samouczek nie powtarza liczby narzędzi.

Przykład kodu — szybki start

Najkrótsza ścieżka wygląda tak. Włącz tryb otagowany wraz z językiem, ustaw tytuł, a następnie dodaj treść.

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

Włącz tryb otagowany przed pierwszym wywołaniem treści. Mechanizm zapisu zamraża tryb w chwili emisji pierwszej strony. Jeśli włączysz go później, NextPDF nie wraca do wcześniej wyemitowanej treści i jej nie taguje. Tytuł dokumentu jest wymagany przez PDF/UA-2, a tryb otagowany ustawia preferencję wyświetlania tytułu w przeglądarce.

Przykład kodu — produkcja

Dodaj semantyczny HTML. Potok odwzorowuje nagłówki, listy, tabele z <th scope>, łącza oraz ilustracje z alt na właściwe typy struktury:

{
  "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.

" } }}">

Następnie uruchom standards-check względem PDF/UA-2 oraz veraPDF --flavour ua2 na wyniku. Wynik kontroli i werdykt veraPDF mają charakter oceny. Wskazują, czy dokument jest przeznaczony do zgodności. O zgodności decyduje veraPDF, a nie NextPDF.

Przypadki brzegowe i pułapki

• Tryb otagowany włączony po dodaniu treści. Każda treść dodana przed włączeniem trybu pozostaje nieotagowana. Kontrola zgłasza błąd dotyczący tagowania treści. Włącz tryb bezpośrednio po utworzeniu dokumentu.
• Obraz informacyjny bez alt. Kontrola zgłasza błąd braku tekstu alternatywnego ilustracji. Podaj tekst alternatywny albo oznacz obraz dekoracyjny jako artefakt (/cookbook/connect/page-artifacts/).
• Pominięty poziom nagłówka. Sekwencja H1, a następnie H3, jest błędem kolejności nagłówków. Przechodź naraz najwyżej o jeden poziom w dół.
• <th> bez scope. Komórka nagłówkowa bez powiązanych komórek danych jest błędem struktury tabeli. Każdej komórce <th> nadaj albo scope="col", albo scope="row".
• Brak tytułu. Dokument bez tytułu jest błędem metadanych. Ustaw tytuł po włączeniu trybu otagowanego.

Wydajność

Budżet podany w nagłówku front matter jest limitem dokumentacyjnym. Tagowanie stanowi część normalnego przebiegu układu.

Uwagi dotyczące bezpieczeństwa

Nie ma tu dodatkowych wymagań poza ogólnymi wytycznymi dotyczącymi transportu Connect: nie zapisuj w dziennikach treści dokumentu ani treści HTML na poziomie logowania dostępnym z zewnątrz.

Zgodność

Odwzorowanie PDF/UA-2

Semantyczny HTML odwzorowuje się na standardowe typy struktury PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). Odwzorowanie jest automatyczne. Po stronie autora leży napisanie semantycznego HTML.

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

Stwierdzenie	Klauzula	reference_id
Struktura logiczna + język → możliwość przeglądania w kolejności czytania	ISO 32000-2 §14.7
Opis alternatywny przechowywany w /Alt	ISO 32000-2 §14.8
Treść w drzewie struktury; o zgodności rozstrzyga weryfikator	PDF/UA-2 §8.2.4

Odwzorowanie WCAG 2.2

Struktura wspiera WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1 oraz 2.4.6 na poziomie treści. Autor treści nadal odpowiada za decyzje redakcyjne na poziomie WCAG.

NextPDF wytwarza wynik przeznaczony do zgodności z PDF/UA-2. Nie deklaruje zgodności. Rozstrzygnięcia o zgodności dokonuje veraPDF lub inny weryfikator. Pomyślny wynik kontroli lub uruchomienia veraPDF jest dowodem na to, że wynik jest przeznaczony do zgodności, a nie certyfikatem wystawionym przez NextPDF.

Kontekst komercyjny

Narzędzia trybu otagowanego i narzędzia treści należą do edycji core. Narzędzie weryfikacyjne standards-check należy do poziomu Pro/Enterprise i rejestruje się tylko wtedy, gdy obok serwera zainstalowany jest nextpdf/premium.

Szczegóły dotyczące Connect

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

Każde narzędzie z tego samouczka wywołuje się tak samo: przez MCP tools/call, punkt końcowy narzędzia REST oraz usługę gRPC. Wszystkie przechodzą przez wspólny moduł wykonawczy narzędzi.

Poziom ryzyka HITL

Włączenie trybu otagowanego oraz korzystanie z narzędzi treści mają poziom ostrożności. Standards-check działa wyłącznie do odczytu. Wyjściowa ścieżka zapisu do pliku wymaga zatwierdzenia, natomiast tryb base64 nie. Zobacz /connect/hitl-risk-tiers/.

Koperta JSON bramki potwierdzenia

Gdy wyjściowa ścieżka zapisu do pliku jest objęta bramką, bramka zwraca kopertę wyzwania oraz token jednorazowego użytku. Token jest powiązany z nazwą narzędzia, wartością nonce oraz 300-sekundowym czasem życia (TTL). Aby kontynuować, wywołaj narzędzie ponownie z arguments._confirmation_token. Zobacz /connect/hitl-risk-tiers/.

Zobacz też

• /cookbook/connect/conformance-mode/ — dyskryminator trybu, na którym opiera się tryb otagowany.
• /cookbook/connect/aria-tagged-pdf/ — odwzorowanie ról landmark.
• /cookbook/connect/page-artifacts/ — wyklucz treść dekoracyjną z drzewa struktury.
• /connect/tool-catalog/ — obliczanie zestawu narzędzi dla danego poziomu.