Tabla de contenidos — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del módulo Toc de NextPDF Pro, NextPDF\Pro\Toc. AutoTocCollector explora el HTML en busca de encabezados H1–H6 y emite objetos de valor TocHeading. AutoTocRenderer pagina esos encabezados y representa cada página del TOC como operadores de flujo de contenido PDF. AutoTocConfig es la configuración de representación inmutable. Los números de página los suministra el llamante o son marcadores de posición secuenciales; el módulo no resuelve referencias cruzadas activas del documento. Esta página expone la API pública, el contrato de comportamiento observable y los modos de fallo. La configuración orientada a tareas y los ejemplos residen en la página de capacidad de la tabla de contenidos.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases Toc son utilizables siempre que nextpdf/pro esté instalado y con licencia.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
AutoTocCollector::__construct()	int $maxDepth = 6	Limita la profundidad al rango 1–6	—	—	La instancia acumula los encabezados recopilados
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Construye, explora y devuelve los encabezados en una sola llamada	list<TocHeading>	—	Ruta rápida estática
AutoTocCollector::scan()	string $html	Coincide con H1–H6, elimina el marcado, decodifica entidades, colapsa espacios en blanco y agrega los encabezados no vacíos	—	—	Muta el estado interno
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Avanza la página en cada encabezado de nivel 0 después del primero	list<TocHeading>	—	Solo numeración de marcador de posición
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Aplica un mapa de índice a página; los índices sin asignar conservan su página actual	list<TocHeading>	—	Páginas reales suministradas por el llamante
AutoTocCollector::getHeadings()	—	Devuelve los encabezados recopilados	list<TocHeading>	—	—
AutoTocCollector::count()	—	Número de encabezados recopilados	int	—	—
AutoTocCollector::reset()	—	Borra los encabezados recopilados	—	—	Reutilizar el recopilador entre exploraciones
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtra por profundidad, pagina y emite un flujo de contenido por página	list<string>	—	Devuelve [] cuando todos los encabezados quedan filtrados
AutoTocConfig::__construct()	14 parámetros tipados (título, profundidad, fuentes, espaciado, márgenes, colores, tamaño de página)	Portador de configuración inmutable	—	—	Readonly; los colores ChartColor predeterminan a negro
AutoTocConfig::default(), ::landscape(), ::letter()	—	Preajustes A4 vertical, A4 horizontal y US Letter	self	—	Fábricas estáticas
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	un valor cada uno	Devuelve una nueva instancia con el campo modificado; withMaxDepth() limita a 1–6	self	—	Fluida, sin mutación
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Derivado
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Derivado
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Siempre ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Objeto de valor de encabezado inmutable	—	—	Readonly; nivel 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	número de página o coordenada Y	Devuelve una nueva instancia con los campos de posición modificados	self	—	Fluida, sin mutación
TocHeading::hasPageNumber()	—	Verdadero cuando hay un número de página asignado	bool	—	—

public function __construct(int $maxDepth = 6)

public static function extract(string $html, int $maxDepth = 6): array

public function scan(string $html): void

public function assignSequentialPages(int $startPage = 1): array

public function assignPageNumbers(array $pageMap): array

public static function render(
    array $headings,
    ?AutoTocConfig $config = null,
): array

public function __construct(
    public string $title = 'Table of Contents',
    public int $maxDepth = 6,
    public float $fontSize = 10.0,
    public float $titleFontSize = 16.0,
    public float $indentPerLevel = 15.0,
    public float $lineHeight = 1.6,
    public bool $showPageNumbers = true,
    public bool $showDotLeader = true,
    public ChartColor $textColor = new ChartColor(0.0, 0.0, 0.0),
    public ChartColor $titleColor = new ChartColor(0.0, 0.0, 0.0),
    public float $leftMargin = 40.0,
    public float $topMargin = 50.0,
    public float $pageWidth = 595.28,
    public float $pageHeight = 841.89,
)

public function entriesPerPage(): int

public function __construct(
    public string $title,
    public int $level,
    public ?int $pageNumber = null,
    public float $y = 0.0,
)

public function withPageNumber(int $pageNumber): self

public function hasPageNumber(): bool

Contrato de comportamiento

Recopilación

AutoTocCollector::scan() coincide con <h1>–<h6> mediante un patrón acotado (sin distinción de mayúsculas, con el punto coincidiendo con el salto de línea) que requiere una etiqueta de apertura y de cierre equilibrada del mismo nivel. El contenido interno de cada coincidencia se despoja de etiquetas, se decodifica como entidades (ENT_QUOTES | ENT_HTML5, UTF-8) y se colapsa en espacios en blanco. Los resultados vacíos se descartan. level es el número de la etiqueta menos uno, por lo que H1 es el nivel 0. Una etiqueta más profunda que maxDepth se omite. extract() es la fábrica de una sola llamada sobre construir, explorar y leer.

Asignación de números de página

Existen dos estrategias explícitas, ambas impulsadas por el llamante.

• assignSequentialPages($startPage) avanza el contador de páginas cuando se alcanza un encabezado de nivel 0 después de la primera entrada, y luego marca cada encabezado.
• assignPageNumbers($pageMap) aplica un mapa de índice a página; un índice sin asignar conserva su número de página existente.

Ninguna estrategia inspecciona un documento ya maquetado.

Representación y paginación

AutoTocRenderer::render() conserva los encabezados cuyo level es inferior a maxDepth, devuelve [] cuando no sobrevive ninguno, y luego divide el resto en fragmentos de AutoTocConfig::entriesPerPage(). Cada fragmento se convierte en una cadena de flujo de contenido. Por entrada, la sangría es leftMargin + level * indentPerLevel; el tamaño de fuente disminuye 0.5 pt por nivel y se limita a un mínimo de 6.0 pt; el nivel 0 usa la clave de fuente negrita y los niveles más profundos la clave regular. Cuando los números de página están habilitados y presentes, un guía de puntos opcional rellena el espacio y el número se alinea a la derecha. El título y cada cadena de entrada se muestran con el operador Tj según ISO 32000-2:2020 §9.4, y cada cadena se escapa para la sintaxis de cadena literal PDF según §7.3.4.2. Un HTML y una configuración idénticos producen encabezados y operadores estables.

Casos límite y modos de fallo

• El marcado de encabezado malformado no se recopila. Un <h2> sin cerrar y sin su </h2> correspondiente no supera el patrón de par equilibrado y se omite.
• El texto de encabezado que queda vacío tras despojar las etiquetas y recortar se descarta.
• maxDepth se limita a 1–6 tanto en el constructor del recopilador como en AutoTocConfig::withMaxDepth(); los valores fuera de rango se corrigen, no se rechazan.
• Los números de página los controla el llamante. Ningún paso de maquetación interno descubre la página real en la que cae un encabezado, por lo que el módulo no puede resolver referencias cruzadas activas.
• El módulo no genera excepciones. render() devuelve un array vacío cuando todos los encabezados quedan filtrados por profundidad; nunca lanza con una entrada vacía.
• El dimensionamiento se reduce al mínimo de max(1, …), por lo que entriesPerPage() es siempre al menos 1 y la paginación siempre avanza.
• El representador produce únicamente operadores dibujables. El llamante coloca los flujos devueltos sobre páginas reales y suministra los recursos /TocFont, /TocBoldFont y /TocTitleFont.

Comportamiento en modo FIPS

En este módulo no ocurre ninguna operación criptográfica, por lo que no existe ningún comportamiento específico del modo FIPS. Nada aquí consume aleatoriedad, hash ni firma.

Conformidad

Afirmación	Estándar	Cláusula
El título y el texto de las entradas del TOC se muestran con el operador de mostrado de texto Tj	ISO 32000-2:2020	§9.4
Las cadenas emitidas se escapan como cadenas literales PDF, con la barra invertida duplicada y los paréntesis escapados	ISO 32000-2:2020	§7.3.4.2
Árbol /Outlines de PDF o enlaces a destinos con nombre	—	No construido (solo operadores de flujo de contenido)
Resolución de referencias cruzadas activas del documento	—	No admitida (números de página suministrados por el llamante)

Todas las cláusulas están parafraseadas; NextPDF no reproduce el texto normativo. Son declaraciones de capacidad, no certificaciones; NextPDF no posee ninguna certificación ni la otorga.

Notas de desarrollo

• Disponibilidad dentro del paquete Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig y TocHeading desde 1.9.0. Todos están vigentes en nextpdf/pro 3.1.0.
• Los colores de AutoTocConfig son valores NextPDF\Pro\Chart\ChartColor. Los colores predeterminados de texto y título son negro (0.0, 0.0, 0.0).
• Empezar desde AutoTocConfig::default(), ::landscape() o ::letter(), y luego encadenar los withers. El objeto es readonly, por lo que cada wither devuelve una nueva instancia.
• Asignar números de página reales con assignPageNumbers() a partir de su propio paso de maquetación; assignSequentialPages() solo produce marcadores de posición.
• entriesPerPage(), lineSpacing() y contentWidth() son derivaciones puras de la configuración; invocarlas para predimensionar la maquetación antes de representar.
• getHeadings(), count() y reset() leen y borran el estado acumulado del recopilador entre exploraciones.

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 espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera de alcance.

Véase también

• Tabla de contenidos (capacidad) — instalación, inicio rápido y ejemplos de producción.
• Merge — Referencia detallada
• Template — Referencia detallada