Oznaczanie artefaktów strony w Connect

W skrócie

Ten przepis pokazuje, jak w transportach Connect opakować elementy paginacji, w tym żywą paginę w nagłówkach i stopkach, numery stron, znaki wodne i tła, w treść oznaczoną jako artefakt. Elementy te nadal pojawiają się na stronie, ale pozostają poza drzewem struktury i kolejnością odczytu używaną przez technologie wspomagające. Narzędzie artefaktów należy do poziomu Enterprise: NextPDF wykrywa je za pomocą sondy class_exists() i rejestruje tylko wtedy, gdy obok serwera zainstalowano nextpdf/premium. Podtyp korzysta z typowanego enuma (Pagination, Layout, Page, Background).

Aby zweryfikować wynik, użyj narzędzia Enterprise do sprawdzania zgodności ze standardami, które raportuje względem PDF/UA-2. Pozytywny wynik oznacza kontrolę wykonaną przez to narzędzie, a nie niezależną certyfikację zgodności.

Instalacja

composer require nextpdf/server

Potwierdź obecność narzędzia artefaktów Enterprise wywołaniem tools/list. Zobacz /connect/tool-catalog/.

Przegląd koncepcyjny

Treść, która nie jest częścią struktury logicznej, oznacza się jako artefakt i wyłącza z kolejności odczytu (PDF/UA-2 §8.3). Artefakty obejmują treść paginacji, układu, strony lub tła i różnią się od treści rzeczywistej (PDF/UA-2 §8.3). Treść rzeczywista jest odzwierciedlana w drzewie struktury; artefakty nie są (PDF/UA-2 §8.2.4).

Narzędzie otwiera sekwencję treści oznaczonej jako artefakt z żądanym podtypem. Wszystkie operacje rysowania wykonane przed odpowiadającym zamknięciem są opakowywane w jej obrębie.

Powierzchnia API

Zweryfikuj nazwy narzędzi w działającym rejestrze za pomocą tools/list. Wiążącym katalogiem jest /connect/tool-catalog/. Ten przepis nie powtarza liczby narzędzi.

Przykład kodu — szybki start

Otwórz artefakt Background, narysuj znak wodny, zamknij go:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

Przykład kodu — środowisko produkcyjne

Zestawiaj każde otwarcie z odpowiadającym mu zamknięciem i sprawdź, czy strona nie zawiera osieroconej treści:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

Po narysowaniu tekstu stopki zamknij sekwencję narzędziem kończącym artefakt i uruchom sprawdzanie zgodności ze standardami względem PDF/UA-2. Drzewo struktury musi zawierać wyłącznie treść główną; znak wodny i stopka muszą zostać wyłączone.

Przypadki brzegowe i pułapki

Nieznany podtyp (na przykład "Header") jest odrzucany. Przekaż jeden z: Pagination, Layout, Page, Background.
Zamknięcie bez otwarcia kończy się niepowodzeniem z komunikatem o zerowej głębokości. Zawsze paruj otwarcie i zamknięcie.
Rysowanie przed jakimkolwiek kontekstem artefaktu lub struktury tworzy osieroconą treść i powoduje naruszenie reguły struktury. Najpierw otwórz kontekst struktury lub artefaktu.
Brak narzędzia. Bez nextpdf/premium narzędzie artefaktów Enterprise nie jest zarejestrowane, a wywołanie kończy się niepowodzeniem z błędem nieznanego narzędzia.

Wydajność

Budżet z frontmatter ma charakter dokumentacyjny. Opakowywanie artefaktów nie dodaje osobnej, mierzalnej fazy.

Uwagi dotyczące bezpieczeństwa

Brak dodatkowych kwestii poza ogólnymi wytycznymi dla transportu Connect.

Zgodność

Mapowanie PDF/UA-2

Podtyp	Przypadek użycia
`Pagination`	Żywa pagina nagłówków/stopek, numery stron, elementy nawigacyjne
`Layout`	Linie, separatory, ozdobne obramowania
`Page`	Pomoce powiązane ze stroną (znaczniki cięcia, pasery)
`Background`	Znaki wodne, wypełnienia tła, elementy identyfikacji wizualnej

Odsyłacz tag → ISO 32000-2 §14.9

Twierdzenie	Klauzula	reference_id
Treść niestrukturalna oznaczona jako artefakt, wyłączona z kolejności odczytu	PDF/UA-2 §8.3
Podtypy artefaktów: pagination/layout/page/background	PDF/UA-2 §8.3
Treść rzeczywista w drzewie struktury; artefakty nie	PDF/UA-2 §8.2.4

Mapowanie WCAG 2.2

Wyłączenie dekoracyjnych elementów z kolejności odczytu wspiera kryterium sukcesu Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) na poziomie treści.

Pozytywny wynik sprawdzania zgodności ze standardami oznacza kontrolę, a nie certyfikację zgodności. Rozstrzygnięcie należy do niezależnego narzędzia kontrolnego.

Kontekst komercyjny

Narzędzie artefaktów należy do poziomu Enterprise i rejestruje się tylko wtedy, gdy obok serwera zainstalowano nextpdf/premium.

Szczegóły dotyczące Connect

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

Te narzędzia wywołujesz tak samo przez MCP tools/call, punkt końcowy narzędzia REST oraz usługę gRPC. Wszystkie trzy korzystają ze współdzielonego wykonawcy narzędzi.

Poziom ryzyka HITL

Emisja artefaktów i rysowanie treści należą do poziomu ostrożności; sprawdzanie zgodności ze standardami jest tylko do odczytu. Domyślnie żadne z nich nie jest approval_required. Zobacz /connect/hitl-risk-tiers/.

Koperta JSON bramki potwierdzenia

Te narzędzia nie uruchamiają bramki, chyba że nadpisanie przez operatora podniesie jedno z nich do approval_required. Koperta i kontrakt jednorazowego tokenu znajdują się w /connect/hitl-risk-tiers/.

Zobacz także

/cookbook/connect/aria-tagged-pdf/ — mapowanie ról punktów orientacyjnych.
/cookbook/connect/figure-caption/ — dostępne grupowanie obrazów.
/connect/tool-catalog/ — obliczanie zestawu narzędzi dla danego poziomu.
/connect/hitl-risk-tiers/ — model ryzyka i bramka.