Structure

Visão geral

Esta página aborda a navegação de documentos e a estrutura lógica: contornos (marcadores), sumários, destinos nomeados e a árvore de estrutura marcada usada para acessibilidade e reflow.


Contornos (Marcadores)

Document.GetOutlines() devolve a árvore de contorno atual como OutlineItem[] ([] quando não há /Outlines); Document.SetOutlines() substitui-a — passar [] remove o contorno completamente. Cada OutlineItem possui um Title, um Dest (um número de página ou um destino nomeado), um Children opcional para aninhamento e 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);

Sumário

Page.AddTOC() renderiza uma lista de objetos TOCEntry — cada um com um title e um número de page alvo — em um retângulo em uma página, com títulos quebrados, linhas de pontos e rótulos de página alinhados à direita. Ele devolve um AddTOCResult que relata quantas entradas foram desenhadas e, quando a caixa é muito pequena, o remainder que não coube.

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 Nomeados

Document.GetNamedDestinations() devolve cada destino nomeado — mesclando a árvore de nomes /Names /Dests e o dicionário legado /Dests — como pares { name, dest }, onde dest é um PageDest ({ page, view }). Esses são os mesmos alvos nomeados que um OutlineItem.Dest ou uma anotação de link podem referenciar pelo nome ao invés de um 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);
}

Árvore de Estrutura Marcada

Document.AutoTag() infer e cria um /StructTreeRoot a partir do layout da página — títulos por agrupamento de tamanho de fonte, parágrafos por blocos de texto, tabelas por geometria de linhas, e decisões por imagem entre /Figure e /Artifact — e devolve um AutoTagReport com contagens para cada tipo de elemento. Document.GetStructTree() lê o StructTreeRoot resultante, ou null quando o documento não está marcado.

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)');

Conteúdo adicionado após a execução de AutoTag() — por exemplo, uma página preenchida depois — não é abrangido por essa passagem e não será marcado duas vezes. StructTreeRoot.Append() e StructElement.MarkContent() são os API de autoria manual ao lado do heurístico: Append() adiciona um elemento filho de um tipo especificado, e MarkContent() marca uma região da página como pertencente a esse elemento.


Dicas e Melhores Práticas

  • Execute Document.AutoTag() uma vez, após o conteúdo da página estar finalizado — ele não remarca conteúdo adicionado depois, portanto marque manualmente tudo que for inserido posteriormente com StructTreeRoot.Append() / StructElement.MarkContent().
  • Passe opts.title para AutoTag() — isso também define /ViewerPreferences /DisplayDocTitle, que PDF/UA requer junto ao título do documento.
  • Um OutlineItem.Dest pode apontar para uma página explícita ou para um destino nomeado ({ name: '...' }) — use destinos nomeados quando o número da página de destino puder mudar à medida que o conteúdo for alterado.
  • Verifique AddTOCResult.remainder quando a paginação automática está desativada — uma caixa de índice muito pequena para cada entrada para de desenhar silenciosamente em vez de transbordar a caixa.

Problemas comuns

ProblemaCausaCorreção
Document.GetStructTree() retorna nullO documento não foi marcadoChame Document.AutoTag() ou Document.CreateStructTree() primeiro
O link de um item de contorno não resolveO seu Dest nomeia um destino que não existe em Document.GetNamedDestinations()Confirme se o destino nomeado existe ou use uma página explícita Dest em vez disso
Page.AddTOC() para antes da última seçãoO alvo rect é pequeno demais para cada entrada e autoPaginate está desativadoAmplie o rect, passe autoPaginate: true ou trate AddTOCResult.remainder
O conteúdo adicionado após AutoTag() está ausente da árvore estruturalAutoTag() marca apenas o conteúdo presente no momento da execuçãoMarque manualmente o conteúdo posterior com StructTreeRoot.Append() / StructElement.MarkContent()

FAQ

Como adiciono marcadores a um PDF?

Crie um array de objetos OutlineItem (Title, Dest, opcional Children) e passe-o para Document.SetOutlines().

Um índice pode ocupar várias páginas?

Sim — passe autoPaginate: true nas opções de Page.AddTOC(), ou verifique AddTOCResult.remainder e chame AddTOC() novamente em uma nova página para o que não coube.

Como deixo um PDF acessível (marcado)?

Chame Document.AutoTag(), que infere títulos, parágrafos, tabelas e figuras a partir do layout da página. Para conteúdo adicionado posteriormente, ou onde o resultado heurístico precise de correção, use StructTreeRoot.Append() e StructElement.MarkContent() diretamente.

Qual é a diferença entre um destino por número de página e um destino nomeado?

Um destino por número de página (PageDest) aponta para uma página explícita numerada a partir de 1. Um destino nomeado (NamedDest) aponta para um nome que o visualizador resolve por meio das tabelas de destinos nomeados do próprio documento — útil quando a página de destino pode mudar.


API Reference Resumo

Classe/MétodoDescrição
Document.GetOutlines() / Document.SetOutlines()Ler ou substituir a árvore de contorno do documento (marcador)
OutlineItemUm nó de contorno: Title, Dest, opcional Children
Page.AddTOC()Renderizar um índice em um retângulo de página
TOCEntry / AddTOCResultDados de uma linha do índice e o resultado de sua renderização
Document.GetNamedDestinations()Liste cada destino nomeado no documento
Document.AutoTag()Inferir e criar uma estrutura de marcação hierárquica a partir do layout da página
Document.GetStructTree() / Document.CreateStructTree()Leia ou crie o StructTreeRoot do documento
StructTreeRoot.Append() / StructElement.Append() / StructElement.MarkContent()Criar ou estender manualmente a estrutura de marcação

Ver também

 Português