Asignar roles de regiones ARIA a un PDF etiquetado con Connect

De un vistazo

Envíe, mediante los transportes de Connect, HTML que use elementos de seccionado de HTML5 y roles de regiones ARIA. El flujo de contenido etiquetado los asigna a los tipos de estructura estándar de PDF 2.0, de modo que la tecnología de asistencia pueda navegar por regiones en lugar de por posición visual. La comprobación de accesibilidad que se usa aquí es de nivel Pro: la herramienta se detecta mediante un sondeo de class_exists() y solo se registra cuando nextpdf/premium está instalado junto al servidor. La creación de documentos y la ingesta de HTML utilizan herramientas del núcleo.

La herramienta de accesibilidad informa de los hallazgos respecto a PDF/UA-2 (ISO 14289-2). Un resultado satisfactorio refleja únicamente la evaluación propia de la herramienta. Es una comprobación de accesibilidad, no una certificación de conformidad independiente. La determinación de conformidad la realiza veraPDF u otro verificador.

Instalación

composer require nextpdf/server

Confirme que la herramienta de accesibilidad Pro esté presente en la implementación en ejecución mediante una llamada a tools/list (consulte /connect/tool-catalog/). Si no aparece, nextpdf/premium no está instalado en esta implementación, por lo que el paso de verificación de la receta no puede ejecutarse.

Panorama conceptual

Los elementos estructurales de agrupación organizan la estructura lógica de un documento en secciones y contenedores similares (ISO 32000-2 §14.8). El flujo de HTML asigna estos elementos:

<aside> y role="complementary" → el tipo estándar Aside de PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Un tipo de estructura no estándar solo es aceptable cuando se asigna mediante rol a un tipo estándar (PDF/UA-2 §8.2.5). El flujo emite el tipo estándar directamente, de modo que no se requiere ninguna asignación de rol manual. El contenido debe reflejarse en el árbol de estructura para que la tecnología de asistencia pueda acceder a él (PDF/UA-2 §8.2.4).

Superficie de la API

Los nombres de las herramientas se verifican con el registro en ejecución mediante tools/list. El catálogo de referencia es /connect/tool-catalog/. Esta receta usa las herramientas del núcleo para crear documentos e ingerir HTML, además de la comprobación de accesibilidad Pro. No repite un recuento fijo de herramientas.

Ejemplo de código — Inicio rápido

Cree un documento PDF 2.0 etiquetado, agregue HTML con roles de regiones y compruebe el resultado (MCP tools/call, en secuencia):

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

Conecte el emisor de contenido etiquetado antes de agregar cualquier HTML. Cree el documento con un idioma definido para que el emisor esté activo desde la primera llamada de contenido.

Ejemplo de código — Producción

Agregue el HTML de regiones y ejecute la comprobación de accesibilidad; trate un estado de no éxito como un resultado normal que debe inspeccionarse, en lugar de como un error de transporte:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

La respuesta de la comprobación informa sobre el árbol de estructura observado y ofrece un resumen de hallazgos de PDF/UA-2. Tanto <aside> como <div role="complementary"> se resuelven en el mismo tipo estándar Aside.

Casos límite y trampas

Emisión etiquetada no activa antes del contenido. Si el documento no se creó con un idioma o modo etiquetado, la primera adición de HTML produce contenido sin etiquetar y la comprobación informa de un fallo de contenido etiquetado. Vuelva a crear el documento con el idioma definido.
Rol en conflicto en un elemento de seccionado (<aside role="navigation">) produce una advertencia. Elimine el rol en conflicto o use un <div>.
Herramienta ausente. Sin nextpdf/premium, la herramienta de accesibilidad Pro no se registra y el paso de verificación falla con un error de herramienta desconocida.

Rendimiento

El presupuesto del front-matter es un límite de documentación. La asignación de regiones forma parte de la pasada normal de maquetación. No añade una fase aparte medible para los documentos típicos.

Notas de seguridad

No hay consideraciones adicionales más allá de la guía general de transportes de Connect: no registre el contenido del documento ni el cuerpo HTML en un nivel de registro que se exporte externamente.

Conformidad

Asignación de PDF/UA-2

HTML	Tipo estándar de PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

Referencia cruzada de etiqueta → ISO 32000-2 §14.9

Afirmación	Cláusula	reference_id
Los elementos de agrupación organizan la estructura lógica en secciones	ISO 32000-2 §14.8
Los tipos no estándar requieren asignación de rol a un tipo estándar	PDF/UA-2 §8.2.5
El contenido debe ser alcanzable a través del árbol de estructura	PDF/UA-2 §8.2.4

Asignación de WCAG 2.2

La navegación por regiones favorece los CC 1.3.1 (Información y relaciones) y 2.4.1 (Evitar bloques) de WCAG 2.2 a nivel de contenido. La estructura reside en el formato PDF. El autor del contenido sigue siendo responsable de las decisiones de autoría a nivel de WCAG.

Un resultado satisfactorio de la herramienta de accesibilidad es una comprobación de accesibilidad, no una certificación de conformidad. La determinación de conformidad con PDF/UA-2 la realiza un verificador independiente (por ejemplo, veraPDF).

Contexto comercial

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

Particularidades de Connect

Disponibilidad de transportes (MCP / REST / gRPC)

create_pdf, add_html y la comprobación de accesibilidad se invocan de forma idéntica mediante MCP tools/call, el punto de conexión de herramientas REST y el servicio gRPC, a través del ejecutor de herramientas compartido.

Nivel de riesgo HITL

La creación de documentos y la ingesta de HTML son de nivel de precaución (ejecución automática, registradas en auditoría). La comprobación de accesibilidad es de solo lectura. Ninguna de estas herramientas tiene approval_required de forma predeterminada. Consulte /connect/hitl-risk-tiers/.

Envoltura JSON de la barrera de confirmación

Estas herramientas no activan la barrera a menos que una anulación de configuración del operador eleve una de ellas a approval_required. Cuando se aplica la barrera, la envoltura del desafío y el contrato de token de un solo uso son los que se documentan en /connect/hitl-risk-tiers/.

Véase también

/cookbook/connect/figure-caption/ — estructura anidada de Figure / Caption.
/cookbook/connect/aria-noteref-pattern/ — roles de referencia de nota al pie y de cuerpo.
/connect/tool-catalog/ — cálculo del conjunto de herramientas por nivel.
/connect/hitl-risk-tiers/ — el modelo de riesgo y la barrera.