Wzorzec odsyłacza i treści przypisu dolnego w Connect

W skrócie

Renderuj odsyłacze i treści przypisów dolnych w Connect, tak aby drzewo struktury zawierało role przypisów PDF 2.0. Marker w treści staje się odsyłaczem footnote/endnote, a tekst przypisu treścią notki; między nimi powstaje wzajemne odwołanie zwrotne. Te same dane wyjściowe obsługują trzy postacie HTML: odnośnik w indeksie górnym, jawna rola Accessible Rich Internet Applications (ARIA) role="doc-noteref" oraz kontener treści <aside class="footnote">. Do weryfikacji używane jest narzędzie dostępności z poziomu Pro. NextPDF wykrywa je za pomocą class_exists() i rejestruje je tylko wtedy, gdy wraz z serwerem zainstalowany jest nextpdf/premium.

Pozytywny wynik narzędzia dostępności jest sprawdzeniem dostępności, a nie niezależną certyfikacją zgodności.

Instalacja

composer require nextpdf/server

Potwierdź dostępność narzędzia dostępności Pro, wywołując tools/list; zobacz /connect/tool-catalog/.

Przegląd koncepcyjny

PDF 2.0 definiuje dedykowane typy struktury footnote/endnote oraz relację między odsyłaczem a jego treścią (PDF/UA-2 §8.2.5). Odsyłacz przypisu dolnego musi być powiązany z jego treścią (PDF/UA-2 §8.2.5), aby czytnik ekranu mógł zapowiedzieć odsyłacz i podążyć za odnośnikiem, żeby odczytać notkę. Zarówno odsyłacz, jak i treść muszą być dostępne przez drzewo struktury (PDF/UA-2 §8.2.4).

Potok rozpoznaje trzy postacie odsyłacza:

<sup><a href="#fn-N">N</a></sup> — skrócona postać odnośnika w indeksie górnym.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — jawna rola Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA); wartość aria-describedby jest przekazywana jako cel odwołania zwrotnego.
<aside class="footnote" id="fn-N">…</aside> (lub role="doc-footnote") — kontener treści, emitowany jako treść notki z wewnętrznym odwołaniem zwrotnym do pasującego odsyłacza.

Powierzchnia API

Zweryfikuj nazwy narzędzi w działającym rejestrze za pomocą tools/list. Katalog wzorcowy znajduje się w /connect/tool-catalog/. Ten przepis korzysta z podstawowych narzędzi dokumentu i HTML oraz ze sprawdzenia dostępności Pro, bez ponownego podawania liczby narzędzi.

Przykład kodu — Szybki start

Utwórz oznaczony dokument z ustawionym językiem, a następnie dodaj odsyłacz w skróconej postaci odnośnika:

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

Przykład kodu — Produkcja

Wyemituj oba odsyłacze i obie treści w pojedynczym dodaniu HTML, a następnie uruchom sprawdzenie:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

Sprawdzenie dostępności raportuje sparowane role reference/body i wzajemne odwołania zwrotne.

Przypadki brzegowe i pułapki

Odsyłacz bez treści (lub treść bez odsyłacza) zostanie zgłoszony przez sprawdzenie; każdy odsyłacz potrzebuje pasującej treści i odwrotnie.
Niezgodność id między aria-describedby a id treści pozostawia parę nierozwiązaną (rozróżnia wielkość liter).
Kotwica w indeksie górnym do zewnętrznego adresu URL jest emitowana jako zwykły odnośnik, a nie odsyłacz przypisu dolnego; dla celu zewnętrznego użyj jawnej roli.
Goły <aside> bez class/role jest traktowany jako punkt orientacyjny, a nie treść notki. Dodaj class="footnote" lub role="doc-footnote".
Brak narzędzia. Bez nextpdf/premium narzędzie dostępności Pro nie jest zarejestrowane, więc weryfikacja kończy się błędem nieznanego narzędzia.

Wydajność

Budżet w nagłówku frontmatter jest limitem dokumentacyjnym; parowanie przypisów dolnych odbywa się w ramach zwykłego przebiegu struktury.

Uwagi dotyczące bezpieczeństwa

Poza ogólnymi wytycznymi dotyczącymi transportu Connect nie dotyczy.

Zgodność

Mapowanie PDF/UA-2

Twierdzenie	Klauzula	reference_id
Typy struktury footnote/endnote oraz relacja reference/body	PDF/UA-2 §8.2.5
Odsyłacz przypisu dolnego jest powiązany z jego treścią	PDF/UA-2 §8.2.5
Odsyłacz i treść osiągalne przez drzewo struktury	PDF/UA-2 §8.2.4

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

Odsyłacz i treść używają standardowych typów struktury footnote/endnote z PDF 2.0. Wzajemne odwołanie zwrotne stanowi kontrakt dostępnego przypisu dolnego.

Mapowanie WCAG 2.2

Powiązany odsyłacz i treść przypisu dolnego na poziomie treści wspierają kryteria Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) oraz SC 2.4.1 (Bypass Blocks).

Pozytywny wynik narzędzia dostępności jest sprawdzeniem dostępności, a nie certyfikacją zgodności; decyzję w tej sprawie podejmuje niezależny weryfikator.

Kontekst komercyjny

Narzędzie sprawdzania dostępności należy do poziomu Pro i rejestruje się tylko wtedy, gdy wraz z serwerem zainstalowany jest nextpdf/premium.

Szczegóły dotyczące Connect

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

create_pdf, add_html oraz sprawdzenie dostępności są wywoływane tak samo przez Model Context Protocol (MCP), REST i gRPC za pośrednictwem współdzielonego wykonawcy narzędzi.

Poziom ryzyka HITL

Tworzenie dokumentu i pobieranie HTML mają poziom ostrożności; sprawdzenie dostępności 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 ustawione przez operatora podniesie któreś z nich do poziomu approval_required. Kontrakt koperty i jednorazowego tokenu znajduje się w /connect/hitl-risk-tiers/.

Zobacz także

/cookbook/connect/aria-tagged-pdf/ — mapowanie ról punktów orientacyjnych.
/cookbook/connect/figure-caption/ — zagnieżdżona struktura Figure / Caption.
/connect/tool-catalog/ — obliczanie zestawu narzędzi dla poszczególnych poziomów.
/connect/hitl-risk-tiers/ — model ryzyka i bramka.