Emitir una figura accesible con un pie mediante Connect

De un vistazo

Enviar un <figure> HTML que contenga un <img> y un <figcaption> mediante los transportes de Connect. La canalización emite un elemento de estructura estándar Figure, anida el pie como hijo Caption y usa el atributo alt para rellenar /Alt. El paso de verificación utiliza la herramienta de accesibilidad de nivel Pro. NextPDF detecta esa herramienta mediante class_exists() y la registra solo cuando nextpdf/premium está instalado junto con el servidor. La creación de documentos y la ingesta de HTML usan herramientas del núcleo.

Un resultado satisfactorio de la herramienta de accesibilidad es una comprobación de accesibilidad, no una certificación independiente de conformidad.

Instalación

composer require nextpdf/server

Confirmar que la herramienta de accesibilidad Pro esté presente con una llamada tools/list. Consultar /connect/tool-catalog/.

Visión general conceptual

Una descripción alternativa proporciona texto para contenido no textual, como una figura (ISO 32000-2 §14.8). El elemento de estructura conserva esa descripción en su entrada /Alt (ISO 32000-2 §14.8). El atributo HTML alt rellena /Alt en la Figure emitida. La canalización emite el <figcaption> como hijo Caption anidado, en lugar de un párrafo hermano, para que el pie permanezca accesible como parte de la figura (PDF/UA-2 §8.2.4).

Superficie de la API

Verificar los nombres de las herramientas con el registro en ejecución mediante tools/list. El catálogo de referencia está en /connect/tool-catalog/. Esta receta usa las herramientas del núcleo para documentos y HTML, además de la comprobación de accesibilidad Pro. No reafirma el número de herramientas.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

Añadir el marcado de la figura. El alt es obligatorio para que la figura sea accesible:

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

Ejecutar la comprobación de accesibilidad e inspeccionar el árbol de estructura del informe. Debe mostrar una sola Figure que contiene /Alt, con exactamente un hijo Caption.

Casos límite y problemas comunes

<img> sin alt. La comprobación indica un error de texto alternativo para la figura. Proporcionar un alt descriptivo o marcar una imagen puramente decorativa como un artefacto (consultar /cookbook/connect/page-artifacts/).
<figcaption> vacío. La canalización emite una advertencia. Proporcionar texto para el pie o eliminar el elemento.
<figcaption> fuera de cualquier <figure>. La canalización lo emite como un pie huérfano. Envolverlo en un <figure>.
Herramienta ausente. Sin nextpdf/premium, la herramienta de accesibilidad Pro no se registra y la verificación falla con un error de herramienta desconocida.

Rendimiento

El presupuesto del front-matter es un tope definido para la documentación. El procesamiento de la figura se ejecuta como parte de la pasada normal de diseño.

Notas de seguridad

No aplica más allá de la orientación general sobre el transporte de Connect.

Conformidad

Correspondencia con PDF/UA-2

Afirmación	Cláusula	reference_id
Descripción alternativa para el contenido no textual	ISO 32000-2 §14.8
Descripción alternativa mantenida en `/Alt`	ISO 32000-2 §14.8
Pie accesible mediante el árbol de estructura	PDF/UA-2 §8.2.4

Referencia cruzada Etiqueta → ISO 32000-2 §14.9

Figure y Caption son tipos de estructura estándar. Anidar el <figcaption> como Caption define el contrato de una figura accesible.

Correspondencia con WCAG 2.2

Una figura con texto alternativo y un pie asociado satisface los criterios de éxito WCAG 2.2 SC 1.1.1 (Contenido no textual) y SC 1.3.1 (Información y relaciones) a nivel de contenido.

Un resultado satisfactorio de la herramienta de accesibilidad es una comprobación de accesibilidad, no una certificación de conformidad. Esa determinación corresponde a un verificador independiente.

Contexto comercial

La herramienta de comprobación de accesibilidad pertenece al nivel Pro y se registra solo cuando nextpdf/premium está instalado junto con el servidor.

Particularidades de Connect

Disponibilidad de transporte (MCP / REST / gRPC)

Invocar create_pdf, add_html y la comprobación de accesibilidad de forma idéntica mediante MCP, REST y gRPC a través del ejecutor de herramientas compartido.

Nivel de riesgo HITL

La creación de documentos y la ingesta de HTML tienen nivel de precaución. La comprobación de accesibilidad es de solo lectura. Ninguna de ellas es approval_required de forma predeterminada. Consultar /connect/hitl-risk-tiers/.

Sobre JSON de la barrera de confirmación

Estas herramientas no activan la barrera salvo que una anulación del operador eleve una de ellas a approval_required. El contrato del sobre y del token de un solo uso está en /connect/hitl-risk-tiers/.

Véase también

/cookbook/connect/aria-tagged-pdf/ — correspondencia de roles de referencia (landmark).
/cookbook/connect/aria-noteref-pattern/ — roles de referencia de nota al pie y de cuerpo.
/cookbook/connect/page-artifacts/ — marcar imágenes decorativas como artefactos.
/connect/tool-catalog/ — cálculo del conjunto de herramientas por nivel.