Marque artefatos de página com o Connect

Visão geral

Esta receita mostra como envolver elementos de paginação, incluindo cabeçalhos e rodapés correntes, números de página, marcas d’água e planos de fundo, em conteúdo marcado como artefato pelos transportes do Connect. Esses elementos continuam aparecendo na página, mas ficam fora da árvore de estrutura e da ordem de leitura da tecnologia assistiva. A ferramenta de artefato é do tier Enterprise: o NextPDF a descobre por meio de uma sondagem class_exists() e a registra somente quando o nextpdf/premium está instalado junto com o servidor. O subtipo usa um enum tipado (Pagination, Layout, Page, Background).

Para verificar a saída, use a ferramenta de verificação de padrões do Enterprise, que gera relatórios com base no PDF/UA-2. Um resultado aprovado representa a verificação feita pela própria ferramenta, não uma certificação independente de conformidade.

Instalação

composer require nextpdf/server

Confirme se a ferramenta de artefato do Enterprise está presente com uma chamada tools/list. Consulte /connect/tool-catalog/.

Visão conceitual

O conteúdo que não faz parte da estrutura lógica é marcado como artefato e excluído da ordem de leitura (PDF/UA-2 §8.3). Os artefatos incluem conteúdo de paginação, layout, página ou plano de fundo e são distintos do conteúdo real (PDF/UA-2 §8.3). O conteúdo real é refletido na árvore de estrutura; os artefatos não (PDF/UA-2 §8.2.4).

A ferramenta abre uma sequência de conteúdo marcado como artefato do subtipo solicitado. Quaisquer operações de desenho que você emitir antes do fechamento correspondente ficam envolvidas nessa sequência.

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 não duplica a contagem de ferramentas.

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

Abra um artefato Background, desenhe a marca d’água e feche-o:

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

Exemplo de código — Produção

Pareie cada abertura com um fechamento e verifique se a página não contém nenhum conteúdo órfão:

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

Depois de desenhar o texto do rodapé, feche o artefato com a ferramenta de fim de artefato e execute a verificação de padrões com base no PDF/UA-2. A árvore de estrutura deve conter apenas o conteúdo do corpo; a marca d’água e o rodapé devem ser excluídos.

Casos extremos & armadilhas

Subtipo desconhecido (por exemplo "Header") é rejeitado. Passe um destes: Pagination, Layout, Page, Background.
Fechar sem uma abertura falha com uma mensagem de profundidade zero. Sempre pareie a abertura e o fechamento.
Desenhar antes de qualquer contexto de artefato ou estrutura produz conteúdo órfão e uma falha de regra de estrutura. Abra primeiro um contexto de estrutura ou artefato.
Ferramenta ausente. Sem o nextpdf/premium, a ferramenta de artefato do Enterprise não é registrada, e a chamada falha com um erro de ferramenta desconhecida.

Desempenho

O orçamento definido no frontmatter é um limite de documentação. Marcar como artefato não adiciona nenhuma fase separada mensurável.

Notas de segurança

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

Conformidade

Mapeamento PDF/UA-2

Subtipo	Caso de uso
`Pagination`	headers/footers correntes, números de página, elementos de navegação
`Layout`	filetes, separadores, bordas decorativas
`Page`	Auxílios vinculados à página (marcas de corte, registro)
`Background`	Marcas d’água, preenchimentos de fundo, identidade visual

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

Afirmação	Cláusula	reference_id
Conteúdo não estrutural marcado como artefato, excluído da ordem de leitura	PDF/UA-2 §8.3
Subtipos de artefato: pagination/layout/page/background	PDF/UA-2 §8.3
Conteúdo real na árvore de estrutura; artefatos não	PDF/UA-2 §8.2.4

Mapeamento WCAG 2.2

Excluir elementos decorativos da ordem de leitura atende às Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) no nível do conteúdo.

Um resultado aprovado na verificação de padrões representa uma checagem, não uma certificação de conformidade. Um verificador independente é quem faz essa determinação.

Contexto comercial

A ferramenta de artefato é do tier Enterprise e é registrada somente quando o nextpdf/premium está instalado junto com o servidor.

Especificidades do Connect

Disponibilidade por transporte (MCP / REST / gRPC)

Você invoca essas ferramentas da mesma forma via MCP tools/call, pelo endpoint de ferramenta REST e pelo serviço gRPC. Os três usam o executor de ferramentas compartilhado.

Nível de risco HITL

A emissão de artefatos e o desenho de conteúdo ficam no nível de cautela; a verificação de padrões é 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 a 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/figure-caption/ — agrupamento acessível de imagens.
/connect/tool-catalog/ — cálculo do conjunto de ferramentas por tier.
/connect/hitl-risk-tiers/ — o modelo de risco e o portão.