Mapeie funções de marco do ARIA para PDF com tags usando o Connect

Visão geral

Envie pelo Connect HTML que use elementos de seccionamento do HTML5 e funções de marco do Accessible Rich Internet Applications (ARIA). O pipeline de conteúdo com tags as mapeia para os tipos de estrutura padrão do PDF 2.0, de modo que a tecnologia assistiva possa navegar por marcos em vez de depender da posição visual. A verificação de acessibilidade usada aqui é de nível Pro: a ferramenta é descoberta por uma sondagem class_exists() e só é registrada quando o nextpdf/premium está instalado junto com o servidor. A criação de documentos e a ingestão de HTML usam ferramentas do core.

A ferramenta de acessibilidade relata constatações em relação ao PDF/UA-2 (ISO 14289-2). Um resultado aprovado representa a avaliação da própria ferramenta. Trata-se de uma verificação de acessibilidade, não de uma certificação de conformidade independente. O veraPDF ou outro verificador determina a conformidade.

Instalação

composer require nextpdf/server

Confirme que a ferramenta de acessibilidade Pro está presente na implantação em execução com uma chamada tools/list (consulte /connect/tool-catalog/). Se ela estiver ausente, o nextpdf/premium não está instalado nessa implantação, portanto a etapa de verificação desta receita não pode ser executada.

Visão conceitual

Os elementos de estrutura de agrupamento organizam a estrutura lógica do documento em seções e contêineres semelhantes (ISO 32000-2 §14.8). O pipeline de HTML mapeia estes elementos:

<aside> e role="complementary" → o tipo padrão Aside do PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Um tipo de estrutura não padrão só é aceitável quando passa por mapeamento de função para um tipo padrão (PDF/UA-2 §8.2.5). O pipeline emite o tipo padrão diretamente, então você não precisa fazer um mapeamento de função manual. O conteúdo precisa estar refletido na árvore de estrutura para que a tecnologia assistiva o alcance (PDF/UA-2 §8.2.4).

Superfície da API

Verifique os nomes das ferramentas em relação ao registro em execução com tools/list. O catálogo oficial é /connect/tool-catalog/. Esta receita usa as ferramentas de criação de documentos e de ingestão de HTML do core, além da verificação de acessibilidade Pro. Ela não declara novamente uma contagem fixa de ferramentas.

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

Crie um documento PDF 2.0 com tags, adicione HTML com funções de marco e verifique-o sequenciando requisições 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" }
  }
}

Conecte o emissor de conteúdo com tags antes de adicionar qualquer HTML. Crie o documento com um idioma definido para que o emissor fique ativo desde a primeira chamada de conteúdo.

Exemplo de código — Produção

Adicione o HTML de marco e execute a verificação de acessibilidade. Trate um status sem sucesso como um resultado normal a inspecionar, não como um erro de transporte:

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

A resposta da verificação relata a árvore de estrutura observada e um resumo das constatações de PDF/UA-2. Tanto <aside> quanto <div role="complementary"> se reduzem ao mesmo tipo padrão Aside.

Casos extremos e pegadinhas

Emissão com tags não ativa antes do conteúdo. Se o documento não foi criado com um idioma / modo com tags, a primeira adição de HTML produz conteúdo sem tags, e a verificação relata uma falha de conteúdo com tags. Recrie o documento com o idioma definido.
Função conflitante em um elemento de seccionamento (<aside role="navigation">) produz um aviso. Remova a função conflitante ou use um <div>.
Ferramenta ausente. Sem o nextpdf/premium, a ferramenta de acessibilidade Pro não é registrada, e a etapa de verificação falha com um erro de ferramenta desconhecida.

Desempenho

O orçamento do frontmatter é um limite de documentação. O mapeamento de marcos faz parte da etapa normal de layout. Ele não adiciona uma fase mensurável separada para documentos típicos.

Notas de segurança

Nenhuma orientação adicional se aplica além da regra geral de transporte do Connect: não registre o conteúdo do documento nem o corpo do HTML em um nível de log enviado externamente.

Conformidade

Mapeamento de PDF/UA-2

HTML	Tipo padrão do PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

Referência cruzada de tag → ISO 32000-2 §14.9

Afirmação	Cláusula	reference_id
Os elementos de agrupamento organizam a estrutura lógica em seções	ISO 32000-2 §14.8
Tipos não padrão exigem mapeamento de função para um tipo padrão	PDF/UA-2 §8.2.5
O conteúdo precisa ser alcançável pela árvore de estrutura	PDF/UA-2 §8.2.4

Mapeamento de WCAG 2.2

A navegação por marcos dá suporte ao critério de sucesso (SC) 1.3.1 (Informações e Relações) e ao SC 2.4.1 (Ignorar Blocos) da WCAG 2.2 no nível do conteúdo. O formato PDF carrega a estrutura. O autor do conteúdo continua responsável pelas decisões de autoria no nível da WCAG.

Um resultado aprovado da ferramenta de acessibilidade é uma verificação de acessibilidade, não uma certificação de conformidade. Um verificador independente (por exemplo, veraPDF) determina a conformidade com PDF/UA-2.

Contexto comercial

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

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

Invoque create_pdf, add_html e a verificação de acessibilidade da mesma forma por MCP tools/call, pelo endpoint de ferramenta REST e pelo serviço gRPC por meio do executor de ferramentas compartilhado.

Nível de risco HITL

A criação de documentos e a ingestão de HTML são de nível de cautela (execução automática, registradas em auditoria). A verificação de acessibilidade é somente leitura. Nenhuma dessas ferramentas é 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 de configuração do operador eleve uma delas a approval_required. Quando submetidas ao gate, o envelope de desafio e o contrato de token de uso único seguem /connect/hitl-risk-tiers/.

Consulte também

/cookbook/connect/figure-caption/ — estrutura Figure / Caption aninhada.
/cookbook/connect/aria-noteref-pattern/ — funções de referência de nota de rodapé e de corpo.
/connect/tool-catalog/ — cálculo do conjunto de ferramentas por nível.
/connect/hitl-risk-tiers/ — modelo de risco e gate.