Emita uma Figure acessível com uma Caption usando o Connect

Visão geral

Envie um <figure> HTML com um <img> e um <figcaption> usando os transportes do Connect. O pipeline emite um elemento de estrutura Figure padrão, aninha a legenda como um elemento filho Caption e usa o atributo alt para preencher /Alt. Verifique o resultado com a ferramenta de acessibilidade do tier Pro. O NextPDF descobre essa ferramenta por meio de class_exists() e a registra apenas quando o nextpdf/premium está instalado junto com o servidor. As ferramentas do Core cuidam da criação do documento e da ingestão de HTML.

Um resultado aprovado pela ferramenta de acessibilidade equivale a uma verificação de acessibilidade, não a uma certificação de conformidade independente.

Instalação

composer require nextpdf/server

Confirme que a ferramenta de acessibilidade Pro está presente usando uma chamada tools/list. Consulte /connect/tool-catalog/.

Visão conceitual

Uma descrição alternativa fornece texto para conteúdo não textual, como uma figura (ISO 32000-2 §14.8). O elemento de estrutura armazena essa descrição na entrada /Alt (ISO 32000-2 §14.8). O atributo alt do HTML preenche /Alt na Figure emitida. O pipeline emite o <figcaption> como um filho Caption aninhado, em vez de um parágrafo irmão, para que a legenda permaneça acessível como parte da figura (PDF/UA-2 §8.2.4).

Superfície da API

Verifique os nomes das ferramentas no registro em execução com tools/list. O catálogo de referência é /connect/tool-catalog/. Esta receita usa as ferramentas Core de documento e HTML, além da verificação de acessibilidade Pro. Ela não reproduz uma contagem de ferramentas.

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

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

Exemplo de código — Produção

Adicione a marcação da figura. O alt é obrigatório para que a figura seja acessível:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

Execute a verificação de acessibilidade e, depois, inspecione a árvore de estrutura informada. Ela mostra uma única Figure com /Alt e exatamente um filho Caption.

Casos extremos e pegadinhas

<img> sem alt. A verificação relata uma falha no texto alternativo da figura. Forneça um alt descritivo ou marque uma imagem puramente decorativa como um artefato (consulte /cookbook/connect/page-artifacts/).
<figcaption> vazio. O pipeline emite um aviso. Forneça o texto da legenda ou remova o elemento.
<figcaption> fora de qualquer <figure>. O pipeline emite o elemento como uma legenda órfã. Envolva-o em um <figure>.
Ferramenta ausente. Sem o nextpdf/premium, a ferramenta de acessibilidade Pro não é registrada, e a verificação falha com erro de ferramenta desconhecida.

Desempenho

O orçamento no front-matter é um limite documentado. O processamento de figuras é executado como parte da passagem normal de layout.

Notas de segurança

Nenhuma orientação adicional se aplica além das diretrizes gerais de transporte do Connect.

Conformidade

Mapeamento PDF/UA-2

Afirmação	Cláusula	reference_id
Descrição alternativa para conteúdo não textual	ISO 32000-2 §14.8
Descrição alternativa mantida em `/Alt`	ISO 32000-2 §14.8
Caption acessível por meio da árvore de estrutura	PDF/UA-2 §8.2.4

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

Figure e Caption são tipos de estrutura padrão. Aninhar o <figcaption> como Caption estabelece o contrato da figura acessível.

Mapeamento WCAG 2.2

Uma figura com texto alternativo e uma legenda associada atende aos critérios SC 1.1.1 (Non-text Content) e SC 1.3.1 (Info and Relationships) das Web Content Accessibility Guidelines (WCAG) 2.2 no nível de conteúdo.

Um resultado aprovado pela ferramenta de acessibilidade equivale a uma verificação de acessibilidade, não a uma certificação de conformidade. Um verificador independente faz essa determinação.

Contexto comercial

A ferramenta de verificação de acessibilidade é do tier Pro e é registrada somente 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 Model Context Protocol (MCP), REST e gRPC por meio do executor de ferramentas compartilhado.

Tier de risco HITL

A criação de documentos e a ingestão de HTML ficam no 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 portão de confirmação

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

Veja também

/cookbook/connect/aria-tagged-pdf/ — mapeamento de funções de marco (landmark).
/cookbook/connect/aria-noteref-pattern/ — referência de nota de rodapé e funções de corpo.
/cookbook/connect/page-artifacts/ — marque imagens decorativas como artefatos.
/connect/tool-catalog/ — cálculo do conjunto de ferramentas por tier.