Patrón de referencia y cuerpo de nota al pie en Connect

En resumen

Representar referencias y cuerpos de notas al pie en los transportes de Connect para que el árbol de estructura conserve los roles de nota al pie de PDF 2.0. El marcador en línea pasa a ser una referencia footnote/endnote y el texto de la nota al pie pasa a ser un cuerpo de nota, con una retrorreferencia recíproca entre ambos. Tres formas HTML generan la misma salida: un enlace dentro de un superíndice, un rol ARIA explícito role="doc-noteref" y un contenedor de cuerpo <aside class="footnote">. La verificación utiliza la herramienta de accesibilidad de nivel Pro. NextPDF la descubre mediante class_exists() y la registra solo cuando nextpdf/premium está instalado junto al servidor.

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

Instalación

composer require nextpdf/server

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

Panorama conceptual

PDF 2.0 define tipos de estructura dedicados footnote/endnote y la relación entre una referencia y su cuerpo (PDF/UA-2 §8.2.5). Una referencia de nota al pie debe estar asociada con su cuerpo (PDF/UA-2 §8.2.5), de modo que un lector de pantalla pueda anunciar la referencia y seguir el enlace para leer la nota. Tanto la referencia como el cuerpo deben ser accesibles a través del árbol de estructura (PDF/UA-2 §8.2.4).

El flujo reconoce tres formas de referencia:

<sup><a href="#fn-N">N</a></sup> — forma abreviada de enlace en superíndice.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — rol DPUB-ARIA explícito; aria-describedby se pasa como destino de la retrorreferencia.
<aside class="footnote" id="fn-N">…</aside> (o role="doc-footnote") — contenedor del cuerpo, emitido como cuerpo de nota con una referencia interna de vuelta a la referencia correspondiente.

Superficie de la API

Verificar los nombres de las herramientas con el registro en ejecución mediante tools/list. El catálogo de referencia es /connect/tool-catalog/. Esta receta usa las herramientas principales de documento y HTML, además de la comprobación de accesibilidad Pro, y no vuelve a declarar un recuento de herramientas.

Ejemplo de código — Inicio rápido

Crear un documento etiquetado con el idioma definido y luego añadir la referencia con la forma abreviada de enlace:

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

Ejemplo de código — Producción

Emitir ambas referencias y ambos cuerpos en una única adición de HTML y luego comprobar:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

La comprobación de accesibilidad informa sobre los roles reference/body emparejados y las retrorreferencias recíprocas.

Casos límite y problemas frecuentes

Referencia sin cuerpo (o cuerpo sin referencia): la comprobación lo informa; cada referencia necesita un cuerpo correspondiente y viceversa.
Discrepancia de id entre aria-describedby y el id del cuerpo deja el par sin resolver (se distinguen mayúsculas y minúsculas).
Un ancla de superíndice hacia una URL externa genera un enlace simple, no una referencia de nota al pie; usar el rol explícito para un destino externo.
<aside> simple sin class/role se trata como un punto de referencia, no como un cuerpo de nota. Añadir class="footnote" o role="doc-footnote".
Herramienta ausente. Sin nextpdf/premium la herramienta de accesibilidad Pro no se registra, por lo que la verificación falla con un error de herramienta desconocida.

Rendimiento

El presupuesto del front-matter es un límite de documentación; el emparejamiento de notas al pie forma parte del paso de estructura normal.

Notas de seguridad

No hay consideraciones adicionales más allá de la guía general del transporte de Connect.

Conformidad

Correspondencia con PDF/UA-2

Afirmación	Cláusula	reference_id
Tipos de estructura footnote/endnote y relación reference/body	PDF/UA-2 §8.2.5
Una referencia de nota al pie está asociada con su cuerpo	PDF/UA-2 §8.2.5
Referencia y cuerpo accesibles a través del árbol de estructura	PDF/UA-2 §8.2.4

Etiqueta → referencia cruzada con ISO 32000-2 §14.9

La referencia y el cuerpo utilizan los tipos de estructura estándar footnote/endnote de PDF 2.0. La retrorreferencia recíproca es el contrato accesible de nota al pie.

Correspondencia con WCAG 2.2

La referencia y el cuerpo de nota al pie asociados respaldan los SC 1.3.1 (Información y relaciones) y SC 2.4.1 (Evitar bloques) de WCAG 2.2 en el nivel de contenido.

Un resultado satisfactorio de la herramienta de accesibilidad es una comprobación de accesibilidad, no una certificación de conformidad; un verificador independiente realiza esa determinación.

Contexto comercial

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

Aspectos específicos de Connect

Disponibilidad de transporte (MCP / REST / gRPC)

create_pdf, add_html y la comprobación de accesibilidad se invocan de la misma forma en MCP, REST y gRPC mediante el 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 es approval_required de forma predeterminada. Consultar /connect/hitl-risk-tiers/.

Envoltorio JSON de la puerta de confirmación

Estas herramientas no activan la puerta a menos que una anulación del operador eleve alguna a approval_required. El envoltorio y el contrato de token de un solo uso se describen en /connect/hitl-risk-tiers/.

Véase también

/cookbook/connect/aria-tagged-pdf/ — correspondencia de roles de punto de referencia.
/cookbook/connect/figure-caption/ — estructura anidada Figure / Caption.
/connect/tool-catalog/ — cálculo del conjunto de herramientas por nivel.
/connect/hitl-risk-tiers/ — el modelo de riesgo y la puerta.