Padrão de referência e corpo de nota de rodapé no Connect

Visão geral

Renderize referências e corpos de notas de rodapé no Connect para que a árvore de estrutura inclua os papéis de nota de rodapé do PDF 2.0. O marcador em linha se torna uma referência footnote/endnote, e o texto da nota de rodapé se torna um corpo de nota, com uma referência cruzada recíproca entre eles. Três formas em HTML produzem a mesma saída: um link dentro de um sobrescrito, um role="doc-noteref" explícito do Accessible Rich Internet Applications (ARIA) e um contêiner de corpo <aside class="footnote">. A verificação usa a ferramenta de acessibilidade da camada Pro. O NextPDF descobre essa ferramenta com class_exists() e a registra somente quando o nextpdf/premium está instalado junto com o servidor.

Um resultado aprovado na ferramenta de acessibilidade é uma verificação de acessibilidade, não uma certificação de conformidade independente.

Instalação

composer require nextpdf/server

Confirme que a ferramenta de acessibilidade Pro está disponível por meio de uma chamada tools/list; consulte /connect/tool-catalog/.

Visão conceitual

O PDF 2.0 define tipos de estrutura footnote/endnote dedicados e a relação entre uma referência e seu corpo (PDF/UA-2 §8.2.5). Uma referência de nota de rodapé deve ser associada ao seu corpo (PDF/UA-2 §8.2.5), para que um leitor de tela possa anunciar a referência e seguir o link para ler a nota. Tanto a referência quanto o corpo devem ser alcançáveis por meio da árvore de estrutura (PDF/UA-2 §8.2.4).

O pipeline reconhece três formas de referência:

<sup><a href="#fn-N">N</a></sup> — atalho de link em sobrescrito.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — papel explícito do Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA); aria-describedby é usado como o alvo da referência cruzada.
<aside class="footnote" id="fn-N">…</aside> (ou role="doc-footnote") — o contêiner do corpo, emitido como um corpo de nota com uma referência interna de volta para a referência correspondente.

Superfície da API

Verifique os nomes das ferramentas no registro em execução com tools/list. O catálogo oficial é /connect/tool-catalog/. Esta receita usa as ferramentas core de documento e HTML, além da verificação de acessibilidade Pro, e não repete a contagem de ferramentas.

Exemplo de código — Início rápido

Crie um documento marcado com um idioma definido e, em seguida, adicione a referência por atalho de link:

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

Exemplo de código — Produção

Emita ambas as referências e ambos os corpos em uma única adição de HTML e, em seguida, execute a verificação:

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

A verificação de acessibilidade relata os papéis reference/body pareados e as referências cruzadas recíprocas.

Casos extremos e pegadinhas

Referência sem corpo (ou corpo sem referência) é relatada pela verificação; toda referência precisa de um corpo correspondente, e vice-versa.
Incompatibilidade de id entre aria-describedby e o id do corpo deixa o par sem resolução (há diferenciação entre maiúsculas e minúsculas).
Âncora em sobrescrito apontando para uma URL externa emite um link simples, não uma referência de nota de rodapé; use o papel explícito para um alvo externo.
Um <aside> isolado sem class/role é tratado como um marco (landmark), não como um corpo de nota. Adicione class="footnote" ou role="doc-footnote".
Ferramenta ausente. Sem o nextpdf/premium, a ferramenta de acessibilidade Pro não é registrada, então a verificação falha com erro de ferramenta desconhecida.

Desempenho

O orçamento do frontmatter é um limite documentado; o emparelhamento de notas de rodapé faz parte da passagem normal de estrutura.

Notas de segurança

Nada se aplica além das orientações gerais de transporte do Connect.

Conformidade

Mapeamento PDF/UA-2

Afirmação	Cláusula	reference_id
Tipos de estrutura footnote/endnote e relação reference/body	PDF/UA-2 §8.2.5
Uma referência de nota de rodapé é associada ao seu corpo	PDF/UA-2 §8.2.5
Referência e corpo alcançáveis por meio da árvore de estrutura	PDF/UA-2 §8.2.4

Tag → referência cruzada com ISO 32000-2 §14.9

A referência e o corpo usam os tipos de estrutura padrão footnote/endnote do PDF 2.0. A referência cruzada recíproca é o contrato de nota de rodapé acessível.

Mapeamento WCAG 2.2

A referência de nota de rodapé associada e seu corpo dão suporte aos critérios de sucesso (SC) 1.3.1 (Info and Relationships) e 2.4.1 (Bypass Blocks) das Web Content Accessibility Guidelines (WCAG) 2.2 no nível do conteúdo.

Um resultado aprovado na ferramenta de acessibilidade é uma verificação de acessibilidade, não uma certificação de conformidade; um verificador independente faz essa determinação.

Contexto comercial

A ferramenta de verificação de acessibilidade é da camada Pro e só é registrada quando o nextpdf/premium está instalado junto com o servidor.

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

create_pdf, add_html e a verificação de acessibilidade são invocados da mesma forma via Model Context Protocol (MCP), REST e gRPC por meio do executor de ferramentas compartilhado.

Camada de risco HITL

A criação de documentos e a ingestão de HTML são de nível de cautela; a verificação de acessibilidade é somente leitura. Nenhuma delas é approval_required por padrão. Consulte /connect/hitl-risk-tiers/.

Envelope JSON do gate de confirmação

Essas ferramentas não acionam o gate, a menos que uma substituição do operador eleve uma delas a approval_required. O contrato do envelope e do token de uso único está em /connect/hitl-risk-tiers/.

Veja também

/cookbook/connect/aria-tagged-pdf/ — mapeamento de papéis de marco (landmark).
/cookbook/connect/figure-caption/ — estrutura aninhada Figure / Caption.
/connect/tool-catalog/ — cálculo do conjunto de ferramentas por camada.
/connect/hitl-risk-tiers/ — o modelo de risco e o gate.