Tabla de contenido

De un vistazo

NextPDF\Pro\Toc recopila encabezados H1–H6 de HTML y renderiza una tabla de contenido paginada y de varios niveles como operadores de flujo de contenido PDF. Los números de página son suministrados por el llamante (o marcadores de posición secuenciales); el módulo no resuelve referencias cruzadas de documento en vivo.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Las clases de Toc se cargan siempre que nextpdf/pro esté instalado; ningún indicador de capacidad en tiempo de ejecución restringe el módulo. Compare ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

El flujo de trabajo tiene dos fases:

• Recopilación. AutoTocCollector::extract($html, maxDepth) escanea el HTML en busca de etiquetas <h1>–<h6> hasta el límite de profundidad, despoja el marcado interno, decodifica las entidades, normaliza los espacios en blanco y emite objetos de valor TocHeading (nivel 0 = H1). Puede asignar números de página secuenciales o aplicar un mapa de índice a página proporcionado por el llamante.
• Renderizado. AutoTocRenderer::render($headings, $config) produce una cadena de flujo de contenido PDF por página de TOC, con sangría por nivel, guías de puntos opcionales y números de página opcionales. Cada línea visible se emite como una operación de presentación de texto Tj según ISO 32000-2:2020 §9.4.

AutoTocConfig es un objeto de valor inmutable, configurado de forma fluida, que controla el título, la profundidad, las fuentes, el espaciado, los márgenes, los colores, el tamaño de página y si se muestran las guías de puntos y los números de página.

Por qué funciona así

La decisión determinante es que el módulo nunca inventa un número de página que no puede conocer. Las páginas de destino reales dependen del documento finalmente maquetado, cuya propiedad recae en el llamante; una suposición se desviaría en silencio cada vez que cambiara la paginación. Por eso la recopilación y el renderizado permanecen desacoplados de la maquetación. AutoTocCollector emite encabezados con páginas nulas o de marcador de posición; los números de página reales llegan únicamente a través de un mapa assignPageNumbers() suministrado por el llamante. El renderizado produce entonces operadores de flujo de contenido simples, dejando la colocación de página al llamante. El resultado se mantiene determinista y honesto: el módulo declara lo que no sabe en lugar de fabricarlo.

Contexto de diseño: Una API que se niega a adivinar.

Contrato de comportamiento

• Entrada. HTML (recopilación) y una lista de TocHeading (renderizado).
• Salida. list<TocHeading> de la recopilación; list<string> de operadores de flujo de contenido PDF (uno por página de TOC) del renderizado.
• Números de página. Asignados secuencialmente, suministrados mediante un mapa de índice a página, o dejados en null. El módulo no calcula las páginas de destino reales a partir de un documento maquetado; no resuelve referencias cruzadas.
• Profundidad. maxDepth se acota a 1–6. Los encabezados más profundos que la profundidad configurada se omiten.
• Determinismo. Para HTML y configuración idénticos, los encabezados recopilados y los operadores renderizados son estables.

Superficie de la API pública

Tipo	Clase	Miembros clave
NextPDF\Pro\Toc\AutoTocCollector	final class	static extract(string $html, int $maxDepth = 6): list<TocHeading>, scan(string $html): void, assignSequentialPages(int $startPage = 1): list<TocHeading>, assignPageNumbers(array $pageMap): list<TocHeading>
NextPDF\Pro\Toc\AutoTocRenderer	final class	static render(array $headings, ?AutoTocConfig $config = null): list<string>
NextPDF\Pro\Toc\AutoTocConfig	final readonly class	default(), landscape(), letter(), withTitle(), withMaxDepth(), withFontSize(), withDotLeader(), withPageNumbers(), withIndentPerLevel(), entriesPerPage(): int
NextPDF\Pro\Toc\TocHeading	final readonly class	string $title, int $level, ?int $pageNumber, float $y, withPageNumber(), withPosition(), hasPageNumber(): bool

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

Ejemplo de código — Producción

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

Casos límite y trampas

• El texto de encabezado vacío (tras despojar las etiquetas) se omite.
• maxDepth se acota a 1–6 tanto en el recopilador como en la configuración; los valores fuera de rango se corrigen, no se rechazan.
• Los números de página son marcadores de posición a menos que el llamante suministre un mapa real; el módulo no ejecuta una pasada de maquetación para descubrir las páginas de destino reales.
• El renderizador emite operadores de flujo de contenido para su colocación en una página; el llamante es responsable de añadir esas páginas al documento.

Rendimiento

La recopilación es una única pasada de expresión regular sobre el HTML. El renderizado es lineal en el número de encabezados, paginado por entriesPerPage(). Consulte performance_budget.

Notas de seguridad

El HTML se escanea con una expresión regular de encabezado acotada y despojo de etiquetas; no se ejecuta ningún HTML y no se siguen referencias externas. El texto renderizado se escapa para la sintaxis de cadenas del flujo de contenido.

Conformidad

Declaración	Cláusula de especificación	Estado
Líneas de TOC emitidas como operaciones de presentación de texto Tj	ISO 32000-2:2020 §9.4	Verificado (conjunto de pruebas unitarias)
Resolución de referencias cruzadas de documento en vivo	—	No admitido (números de página suministrados por el llamante)

Alternativa / respaldo de Core

No hay ningún generador de TOC en Core. El HTML de origen de los encabezados normalmente proviene del pipeline HTML de Core. Consulte /modules/core/html/.

Nota sobre el límite de Enterprise

Este módulo recopila encabezados y renderiza operadores de TOC. No realiza resolución de referencias cruzadas en todo el documento, generación de índices ni sincronización del árbol de marcadores; esas cuestiones quedan fuera del alcance.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Referencia de TOC
• Merge
• Template
• Pipeline HTML de Core