Marcare gli artefatti di pagina in Connect

In sintesi

Questa ricetta mostra come racchiudere gli elementi di impaginazione — intestazioni e piè di pagina correnti, numeri di pagina, filigrane, sfondi — in contenuto marcato come artefatto nei trasporti Connect. Questi elementi continuano a comparire sulla pagina, ma restano fuori dall’albero della struttura e dall’ordine di lettura delle tecnologie assistive. Lo strumento per artefatti è di livello Enterprise: NextPDF lo rileva tramite un controllo class_exists() e lo registra solo quando nextpdf/premium è installato insieme al server. Il sottotipo è rappresentato da un enum tipizzato (Pagination, Layout, Page, Background).

Per la verifica, usare lo strumento Enterprise di controllo degli standard, che restituisce un esito rispetto a PDF/UA-2. Un esito positivo rappresenta il risultato del controllo eseguito dallo strumento, non una certificazione di conformità indipendente.

Installazione

composer require nextpdf/server

Verificare che lo strumento per artefatti Enterprise sia presente con una chiamata tools/list. Vedere /connect/tool-catalog/.

Panoramica concettuale

Il contenuto che non fa parte della struttura logica viene marcato come artefatto ed escluso dall’ordine di lettura (PDF/UA-2 §8.3). Gli artefatti corrispondono a contenuti di impaginazione, layout, pagina o sfondo, distinti dal contenuto reale (PDF/UA-2 §8.3). Il contenuto reale è rappresentato nell’albero della struttura; gli artefatti no (PDF/UA-2 §8.2.4).

Lo strumento apre una sequenza di contenuto marcato come artefatto del sottotipo richiesto. Qualsiasi operazione di disegno emessa prima della chiusura corrispondente vi viene racchiusa.

Superficie API

Verificare i nomi degli strumenti rispetto al registro attivo con tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta non ripete il conteggio degli strumenti.

Esempio di codice — Avvio rapido

Aprire un artefatto Background, disegnare la filigrana e chiuderlo:

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

Esempio di codice — Produzione

Abbinare ogni apertura a una chiusura e verificare che la pagina non contenga contenuto orfano:

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

Dopo aver disegnato il testo del piè di pagina, chiudere con lo strumento di fine artefatto ed eseguire il controllo degli standard rispetto a PDF/UA-2. L’albero della struttura deve contenere solo il contenuto del corpo del documento; la filigrana e il piè di pagina devono essere esclusi.

Casi limite e insidie

Un sottotipo sconosciuto (per esempio "Header") viene rifiutato. Passare uno tra Pagination, Layout, Page, Background.
Una chiusura senza apertura genera un errore con un messaggio di profondità zero. Abbinare sempre apertura e chiusura.
Disegnare prima di qualsiasi contesto di artefatto o di struttura produce contenuto orfano e una violazione delle regole di struttura. Aprire prima un contesto di struttura o di artefatto.
Strumento assente. Senza nextpdf/premium, lo strumento per artefatti Enterprise non viene registrato e la chiamata fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget nel front-matter è un limite indicato a fini documentali. L’incapsulamento come artefatto non aggiunge alcuna fase separata misurabile.

Note di sicurezza

Non vi sono indicazioni specifiche oltre alle linee guida generali sul trasporto Connect.

Conformità

Mappatura PDF/UA-2

Sottotipo	Caso d’uso
`Pagination`	headers/footers correnti, numeri di pagina, elementi di navigazione
`Layout`	linee, separatori, bordi decorativi
`Page`	Ausili legati alla pagina (segni di taglio, registro)
`Background`	Filigrane, riempimenti di sfondo, branding

Tag → riferimento incrociato ISO 32000-2 §14.9

Affermazione	Clausola	reference_id
Contenuto non strutturale marcato come artefatto, escluso dall’ordine di lettura	PDF/UA-2 §8.3
Sottotipi di artefatto: pagination/layout/page/background	PDF/UA-2 §8.3
Contenuto reale nell’albero della struttura; artefatti no	PDF/UA-2 §8.2.4

Mappatura WCAG 2.2

Escludere gli elementi decorativi dall’ordine di lettura supporta, a livello di contenuto, il criterio di successo WCAG 2.2 SC 1.3.1 (Info and Relationships).

Un esito positivo del controllo degli standard è una verifica, non una certificazione di conformità. Questa determinazione spetta a un verificatore indipendente.

Contesto commerciale

Lo strumento per artefatti è di livello Enterprise e si registra solo quando nextpdf/premium è installato insieme al server.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Questi strumenti si invocano in modo identico tramite MCP tools/call, l’endpoint dello strumento REST e il servizio gRPC, sempre attraverso l’esecutore di strumenti condiviso.

Livello di rischio HITL

L’emissione di artefatti e il disegno dei contenuti rientrano nel livello cautela; il controllo degli standard è di sola lettura. Nessuno di essi è approval_required per impostazione predefinita. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Questi strumenti non attivano il gate, salvo che un override dell’operatore non imposti uno di essi su approval_required. Il contratto dell’envelope e del token monouso è in /connect/hitl-risk-tiers/.

Vedere anche

/cookbook/connect/aria-tagged-pdf/ — mappatura dei ruoli landmark.
/cookbook/connect/figure-caption/ — raggruppamento accessibile delle immagini.
/connect/tool-catalog/ — calcolo dell’insieme di strumenti per livello.
/connect/hitl-risk-tiers/ — il modello di rischio e il gate.