Generare un elemento Figure accessibile con Caption

In sintesi

Inviare tramite i trasporti Connect una <figure> HTML contenente un <img> e una <figcaption>. Il flusso emette un elemento di struttura standard Figure, annida la didascalia come elemento figlio Caption e usa l’attributo alt per popolare /Alt. Il passaggio di verifica usa lo strumento di accessibilità di livello Pro. NextPDF rileva quello strumento tramite class_exists() e lo registra solo quando nextpdf/premium è installato insieme al server. La creazione del documento e l’acquisizione HTML usano gli strumenti core.

Un esito positivo dello strumento di accessibilità è una verifica di accessibilità, non una certificazione di conformità indipendente.

Installazione

composer require nextpdf/server

Verificare che lo strumento di accessibilità Pro sia presente con una chiamata tools/list. Vedere /connect/tool-catalog/.

Panoramica concettuale

Una descrizione alternativa fornisce testo per i contenuti non testuali, come una figura (ISO 32000-2 §14.8). L’elemento di struttura conserva quella descrizione nella propria voce /Alt (ISO 32000-2 §14.8). L’attributo HTML alt popola /Alt nell’elemento Figure emesso. Il flusso emette la <figcaption> come elemento figlio Caption annidato, anziché come paragrafo allo stesso livello, così la didascalia resta raggiungibile come parte della figura (PDF/UA-2 §8.2.4).

Superficie API

Verificare i nomi degli strumenti nel registry in esecuzione con tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta usa gli strumenti core per documenti e HTML, oltre alla verifica di accessibilità Pro. Non ripete il conteggio degli strumenti.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Aggiungere il markup della figura. L’alt è obbligatorio affinché la figura sia accessibile:

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

Eseguire la verifica di accessibilità e ispezionare l’albero della struttura riportato. Il risultato mostra una singola Figure che contiene /Alt, con esattamente un figlio Caption.

Casi limite e insidie

• <img> senza alt. La verifica segnala un errore relativo al testo alternativo della figura. Fornire un alt descrittivo, oppure contrassegnare un’immagine puramente decorativa come artifact (vedere /cookbook/connect/page-artifacts/).
• <figcaption> vuota. Il flusso genera un avviso. Fornire il testo della didascalia o rimuovere l’elemento.
• <figcaption> al di fuori di qualsiasi <figure>. Il flusso la emette come didascalia orfana. Racchiuderla in una <figure>.
• Strumento assente. Senza nextpdf/premium, lo strumento di accessibilità Pro non è registrato e la verifica fallisce con un errore di strumento non riconosciuto.

Prestazioni

Il budget nel front-matter è un limite documentale. La gestione delle figure avviene nel normale passaggio di layout.

Note di sicurezza

Non applicabile, oltre alle indicazioni generali sui trasporti Connect.

Conformità

Mappatura PDF/UA-2

Dichiarazione	Clausola
Descrizione alternativa per i contenuti non testuali	ISO 32000-2 §14.8
Descrizione alternativa conservata in /Alt	ISO 32000-2 §14.8
Caption raggiungibile tramite l’albero della struttura	PDF/UA-2 §8.2.4

Riferimento incrociato tag → ISO 32000-2 §14.9

Figure e Caption sono tipi di struttura standard. Annidare la <figcaption> come Caption fa parte del contratto della figura accessibile.

Mappatura WCAG 2.2

Una figura con testo alternativo e didascalia associata supporta i criteri WCAG 2.2 SC 1.1.1 (Non-text Content) e SC 1.3.1 (Info and Relationships) a livello di contenuto.

Un esito positivo dello strumento di accessibilità è una verifica di accessibilità, non una certificazione di conformità. Tale determinazione spetta a un verificatore indipendente.

Contesto commerciale

Lo strumento di verifica dell’accessibilità è di livello Pro e viene registrato solo quando nextpdf/premium è installato insieme al server.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

create_pdf, add_html e la verifica di accessibilità vengono invocati nello stesso modo su MCP, REST e gRPC tramite l’esecutore di strumenti condiviso.

Livello di rischio HITL

La creazione del documento e l’acquisizione HTML sono di livello caution. La verifica di accessibilità è di sola lettura. Nessuno di questi strumenti è 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 imposti uno di essi su approval_required. L’envelope e il contratto del token monouso sono in /connect/hitl-risk-tiers/.

Vedere anche

• /cookbook/connect/aria-tagged-pdf/ — mappatura dei ruoli landmark.
• /cookbook/connect/aria-noteref-pattern/ — riferimento alla nota a piè di pagina e ruoli del corpo.
• /cookbook/connect/page-artifacts/ — contrassegnare le immagini decorative come artifact.
• /connect/tool-catalog/ — calcolo dell’insieme di strumenti per livello.