Structure
Visión general
Esta página cubre la navegación del documento y la estructura lógica: contornos (marcadores), tablas de contenido, destinos nombrados y el árbol de estructura etiquetado utilizado para accesibilidad y reflujo.
Contornos (Marcadores)
Document.GetOutlines() devuelve el árbol de contorno actual como OutlineItem[] ([] cuando no hay /Outlines); Document.SetOutlines() lo reemplaza — pasar [] elimina el contorno por completo. Cada OutlineItem tiene un Title, un Dest (un número de página o un destino nombrado), Children opcional para anidamiento, y estilo (Color, Bold, Italic, Open).
const items: OutlineItem[] = sections.map((s) => {
const item: OutlineItem = { Title: s.title, Dest: { name: s.dest } };
if (s.subtype === 'sales') {
item.Open = true;
item.Children = ['Pasta', 'Pizza', 'Antipasti']
.map((cat) => ({ Title: cat, Dest: { name: s.dest } }));
}
return item;
});
doc.SetOutlines(items);Tabla de contenido
Page.AddTOC() representa una lista de objetos TOCEntry — cada uno con un title y un número de page objetivo — dentro de un rectángulo en una página, con títulos ajustados, guías de puntos y etiquetas de página alineadas a la derecha. Devuelve un AddTOCResult que informa cuántas entradas se dibujaron y, cuando el cuadro es demasiado pequeño, el remainder que no cabía.
page.AddTOC(
sections.map((s, i) => ({ title: `${i + 1}. ${s.title}`, page: s.page.Number })),
[72, 160, 400, 400],
{ font: 'Helvetica', fontSize: 13, rowGap: 18 },
);Destinos nombrados
Document.GetNamedDestinations() devuelve cada destino nombrado — combinando el árbol de nombres /Names /Dests y el diccionario heredado /Dests — como pares { name, dest }, donde dest es un PageDest ({ page, view }). Estos son los mismos objetivos nombrados que un OutlineItem.Dest o una anotación de enlace pueden referenciar por nombre en lugar de un número de página explícito.
const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));
for (const { name, dest } of doc.GetNamedDestinations()) {
console.log(name, '-> page', dest.page);
}Árbol de Estructura Etiquetada
Document.AutoTag() infiere y crea un /StructTreeRoot a partir del diseño de página — encabezados por agrupamiento de tamaño de fuente, párrafos por bloques de texto, tablas por geometría de líneas, y decisiones /Figure vs. /Artifact por imagen — y devuelve un AutoTagReport con recuentos para cada tipo de elemento. Document.GetStructTree() lee de nuevo el StructTreeRoot resultante, o null cuando el documento no está etiquetado.
const report = doc.AutoTag({ lang: 'en-US', title: 'Quarterly Report', tables: true });
console.log(report.headings, report.paragraphs, report.tables, report.figures);
const tree = doc.GetStructTree();
console.log(tree ? tree.GetText() : '(no structure tree)');El contenido añadido después de que AutoTag() ya se haya ejecutado —por ejemplo, una página completada posteriormente— no está cubierto por esa pasada y no se etiquetará doblemente. StructTreeRoot.Append() y StructElement.MarkContent() son la API de autoría manual junto a la heurística: Append() añade un elemento hijo de un tipo dado, y MarkContent() marca una región de la página como perteneciente a ese elemento.
Consejos y Mejores Prácticas
- Ejecute
Document.AutoTag()una sola vez, después de que el contenido de la página sea definitivo — no vuelve a etiquetar el contenido añadido posteriormente, así que etiquete manualmente cualquier cosa añadida después conStructTreeRoot.Append()/StructElement.MarkContent(). - Pase
opts.titleaAutoTag()— también establece/ViewerPreferences /DisplayDocTitle, que PDF/UA requiere junto con el título del documento. - Un
OutlineItem.Destpuede apuntar a una página explícita o a un destino nombrado ({ name: '...' }) — utilice destinos nombrados cuando el número de página objetivo pueda cambiar a medida que el contenido se modifique. - Verifique
AddTOCResult.remaindercuando la paginación automática está desactivada — una caja de tabla de contenido demasiado pequeña para cada entrada deja de dibujarse silenciosamente en lugar de desbordarse.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
Document.GetStructTree() devuelve null | El documento no ha sido etiquetado | Llame a Document.AutoTag() o Document.CreateStructTree() primero |
| El enlace de un elemento del esquema no se resuelve | Su Dest nombra un destino que no existe en Document.GetNamedDestinations() | Confirma que el destino nombrado exista, o usa una página explícita Dest en su lugar |
Page.AddTOC() se detiene antes de la última sección | El objetivo rect es demasiado pequeño para cada entrada y autoPaginate está desactivado | Amplía el rect, pasa autoPaginate: true, o maneja AddTOCResult.remainder |
El contenido añadido después de AutoTag() falta en el árbol de estructura | AutoTag() solo etiqueta el contenido presente cuando se ejecutó | Etiqueta manualmente el contenido posterior con StructTreeRoot.Append() / StructElement.MarkContent() |
FAQ
¿Cómo añado marcadores a un PDF?
Construya una matriz de objetos OutlineItem (Title, Dest, Children opcional) y pásela a Document.SetOutlines().
¿Puede una tabla de contenido abarcar varias páginas?
Sí — pase autoPaginate: true en las opciones de Page.AddTOC(), o verifique AddTOCResult.remainder y llame a AddTOC() nuevamente en una nueva página para lo que no haya cabido.
¿Cómo hago que un PDF sea accesible (etiquetado)?
Llame a Document.AutoTag(), que infiere encabezados, párrafos, tablas y figuras a partir del diseño de la página. Para contenido añadido después, o donde el resultado heurístico necesite corrección, use StructTreeRoot.Append() y StructElement.MarkContent() directamente.
¿Cuál es la diferencia entre un destino por número de página y un destino nombrado?
Un destino por número de página (PageDest) apunta a una página explícita numerada a partir de 1. Un destino nombrado (NamedDest) apunta a un nombre que el visor resuelve mediante las propias tablas de destinos nombrados del documento — útil cuando la página de destino podría desplazarse.
Resumen de API Reference
| Clase/Método | Descripción |
|---|---|
Document.GetOutlines() / Document.SetOutlines() | Leer o reemplazar el árbol de esquema del documento (marcador) |
OutlineItem | Un nodo de esquema: Title, Dest, opcional Children |
Page.AddTOC() | Renderizar una tabla de contenidos en un rectángulo de página |
TOCEntry / AddTOCResult | Los datos de una fila de TOC y el resultado de dibujarla |
Document.GetNamedDestinations() | Enumera cada destino nombrado en el documento |
Document.AutoTag() | Infiera y cree un árbol de estructura etiquetado a partir del diseño de la página |
Document.GetStructTree() / Document.CreateStructTree() | Leer o crear el StructTreeRoot del documento |
StructTreeRoot.Append() / StructElement.Append() / StructElement.MarkContent() | Crear manualmente o ampliar el árbol de estructura |