Marcare gli artefatti di pagina

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
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.