Marcar artefactos de página mediante Connect

De un vistazo

Esta receta envuelve los elementos de paginación —encabezados y pies de página recurrentes, números de página, marcas de agua y fondos— en contenido marcado como artefacto mediante los transportes de Connect. Estos elementos siguen apareciendo en la página, pero quedan fuera del árbol de estructura y del orden de lectura de las tecnologías de asistencia. La herramienta de artefactos pertenece a la edición Enterprise: NextPDF la detecta mediante una comprobación con class_exists() y la registra únicamente cuando nextpdf/premium está instalado junto al servidor. El subtipo es una enumeración tipada (Pagination, Layout, Page, Background).

Para verificarlo, usar la herramienta de comprobación de estándares de la edición Enterprise, que informa en relación con PDF/UA-2. Un resultado satisfactorio corresponde a la comprobación realizada por la herramienta, no a una certificación de conformidad independiente.

Instalación

composer require nextpdf/server

Confirmar que la herramienta de artefactos Enterprise está presente con una llamada tools/list. Consultar /connect/tool-catalog/.

Descripción conceptual

El contenido que no forma parte de la estructura lógica se marca como artefacto y se excluye del orden de lectura (PDF/UA-2 §8.3). Los artefactos son contenido de paginación, diseño, página o fondo que se distingue del contenido real (PDF/UA-2 §8.3). El contenido real se refleja en el árbol de estructura; los artefactos no (PDF/UA-2 §8.2.4).

La herramienta abre una secuencia de contenido marcado como artefacto del subtipo solicitado. Cualquier operación de dibujo que se emita antes del cierre correspondiente queda envuelta en ella.

Superficie de la API

Verificar los nombres de las herramientas con respecto al registro en ejecución mediante tools/list. El catálogo de referencia es /connect/tool-catalog/. Esta receta no repite el recuento de herramientas.

Ejemplo de código — Inicio rápido

Abrir un artefacto de subtipo Background, dibujar la marca de agua y cerrarlo:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

Ejemplo de código — Producción

Emparejar cada apertura con un cierre y verificar que la página no contenga contenido huérfano:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

Después de dibujar el texto del pie de página, cerrarlo con la herramienta de fin de artefacto y ejecutar la comprobación de estándares con respecto a PDF/UA-2. El árbol de estructura debe contener únicamente el contenido del cuerpo; la marca de agua y el pie de página deben quedar excluidos.

Casos límite y problemas habituales

Un subtipo desconocido (por ejemplo "Header") se rechaza. Pasar uno de los siguientes: Pagination, Layout, Page, Background.
Cerrar sin una apertura produce un error con un mensaje de profundidad cero. Emparejar siempre la apertura y el cierre.
Dibujar antes de cualquier contexto de artefacto o de estructura produce contenido huérfano y un fallo de regla de estructura. Abrir primero un contexto de estructura o de artefacto.
Herramienta ausente. Sin nextpdf/premium, la herramienta de artefactos Enterprise no se registra y la llamada falla con un error de herramienta desconocida.

Rendimiento

El presupuesto del front-matter es un límite documental. El envoltorio de artefacto no añade ninguna fase adicional medible.

Notas de seguridad

No hay requisitos adicionales más allá de las indicaciones generales sobre los transportes de Connect.

Conformidad

Correspondencia con PDF/UA-2

Subtipo	Caso de uso
`Pagination`	Encabezados y pies de página recurrentes (headers/footers), números de página, elementos de navegación
`Layout`	Reglas, separadores, bordes decorativos
`Page`	Ayudas vinculadas a la página (marcas de corte y registro)
`Background`	Marcas de agua, rellenos de fondo, marca corporativa

Etiqueta → referencia cruzada con ISO 32000-2 §14.9

Afirmación	Cláusula	reference_id
Contenido no estructural marcado como artefacto, excluido del orden de lectura	PDF/UA-2 §8.3
Subtipos de artefacto: pagination/layout/page/background	PDF/UA-2 §8.3
Contenido real en el árbol de estructura; los artefactos no	PDF/UA-2 §8.2.4

Correspondencia con WCAG 2.2

Excluir los elementos decorativos del orden de lectura favorece el cumplimiento del criterio WCAG 2.2 SC 1.3.1 (Información y relaciones) a nivel de contenido.

Un resultado satisfactorio en la comprobación de estándares es una comprobación, no una certificación de conformidad. Esa determinación corresponde a un verificador independiente.

Contexto comercial

La herramienta de artefactos es de la edición Enterprise y se registra únicamente cuando nextpdf/premium está instalado junto al servidor.

Particularidades de Connect

Disponibilidad de transportes (MCP / REST / gRPC)

Estas herramientas se invocan de forma idéntica mediante MCP tools/call, el endpoint de herramientas REST y el servicio gRPC, todos por medio del ejecutor de herramientas compartido.

Nivel de riesgo HITL

La emisión de artefactos y el dibujo de contenido son de nivel de precaución; la comprobación de estándares es de solo lectura. Ninguna de ellas 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 una de ellas a approval_required. El contrato del envoltorio y del token de un solo uso se documenta 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/ — agrupación accesible de imágenes.
/connect/tool-catalog/ — cálculo del conjunto de herramientas por edición.
/connect/hitl-risk-tiers/ — modelo de riesgo y puerta de confirmación.