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 con StructTreeRoot.Append() / StructElement.MarkContent().
  • Pase opts.title a AutoTag() — también establece /ViewerPreferences /DisplayDocTitle, que PDF/UA requiere junto con el título del documento.
  • Un OutlineItem.Dest puede 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.remainder cuando 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

ProblemaCausaSolución
Document.GetStructTree() devuelve nullEl documento no ha sido etiquetadoLlame a Document.AutoTag() o Document.CreateStructTree() primero
El enlace de un elemento del esquema no se resuelveSu 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ónEl objetivo rect es demasiado pequeño para cada entrada y autoPaginate está desactivadoAmplía el rect, pasa autoPaginate: true, o maneja AddTOCResult.remainder
El contenido añadido después de AutoTag() falta en el árbol de estructuraAutoTag() 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étodoDescripción
Document.GetOutlines() / Document.SetOutlines()Leer o reemplazar el árbol de esquema del documento (marcador)
OutlineItemUn nodo de esquema: Title, Dest, opcional Children
Page.AddTOC()Renderizar una tabla de contenidos en un rectángulo de página
TOCEntry / AddTOCResultLos 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

Ver también

 Español