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 comStructTreeRoot.Append()/StructElement.MarkContent(). - Passe
opts.titleparaAutoTag()— isso também define/ViewerPreferences /DisplayDocTitle, que PDF/UA requer junto ao título do documento. - Um
OutlineItem.Destpode 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.remainderquando 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
| Problema | Causa | Correção |
|---|---|---|
Document.GetStructTree() retorna null | O documento não foi marcado | Chame Document.AutoTag() ou Document.CreateStructTree() primeiro |
| O link de um item de contorno não resolve | O 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ção | O alvo rect é pequeno demais para cada entrada e autoPaginate está desativado | Amplie o rect, passe autoPaginate: true ou trate AddTOCResult.remainder |
O conteúdo adicionado após AutoTag() está ausente da árvore estrutural | AutoTag() marca apenas o conteúdo presente no momento da execução | Marque 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étodo | Descrição |
|---|---|
Document.GetOutlines() / Document.SetOutlines() | Ler ou substituir a árvore de contorno do documento (marcador) |
OutlineItem | Um nó de contorno: Title, Dest, opcional Children |
Page.AddTOC() | Renderizar um índice em um retângulo de página |
TOCEntry / AddTOCResult | Dados 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 |