Structure

Structure

Questa pagina copre la navigazione del documento e la struttura logica: outline (segnalibri), indici, destinazioni nominate e l’albero di struttura taggato utilizzato per l’accessibilità e il reflow.

Outline (Segnalibri)

Document.GetOutlines() restituisce l’albero di outline corrente come OutlineItem[] ([] quando non esiste alcun /Outlines); Document.SetOutlines() lo sostituisce — passando [] si rimuove completamente l’outline. Ogni OutlineItem ha un Title, un Dest (un numero di pagina o una destinazione nominata), opzionale Children per l’annidamento, e uno stile (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);

Indice

Page.AddTOC() genera un elenco di oggetti TOCEntry — ciascuno con un title e un numero di destinazione page — in un rettangolo su una pagina, con titoli a capo, puntini di raccordo e etichette di pagina allineate a destra. Restituisce un AddTOCResult che segnala quante voci sono state disegnate e, se la casella è troppo piccola, il remainder che non è stato inserito.

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 },
);

Destinazioni nominate

Document.GetNamedDestinations() restituisce ogni destinazione denominata — fondendo l’albero dei nomi /Names /Dests e il dizionario legacy /Dests — come coppie { name, dest }, dove dest è un PageDest ({ page, view }). Questi sono gli stessi obiettivi denominati a cui un OutlineItem.Dest o un’annotazione di collegamento possono fare riferimento per nome anziché con un numero di pagina esplicito.

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));
for (const { name, dest } of doc.GetNamedDestinations()) {
  console.log(name, '-> page', dest.page);
}

Albero di Struttura Tagged

Document.AutoTag() deduce e crea un /StructTreeRoot dalla disposizione della pagina — intestazioni mediante raggruppamento per dimensione del carattere, paragrafi per blocchi di testo, tabelle per geometria delle linee, e decisioni per-immagine /Figure vs. /Artifact — e restituisce un AutoTagReport con i conteggi per ciascun tipo di elemento. Document.GetStructTree() legge nuovamente il StructTreeRoot risultante, o null quando il documento non è taggato.

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

Il contenuto aggiunto dopo che AutoTag() è già stato eseguito — ad esempio una pagina inserita in seguito — non è coperto da quel passaggio e non verrà double-taggato. StructTreeRoot.Append() e StructElement.MarkContent() sono le API di authoring manuale accanto a quella euristica: Append() aggiunge un elemento figlio di un tipo specificato, e MarkContent() segna una regione di pagina come appartenente a quell’elemento.

Suggerimenti e best practice

• Esegui Document.AutoTag() una sola volta, dopo che il contenuto della pagina è definitivo — non rietichetta il contenuto aggiunto successivamente, quindi etichetta manualmente tutto ciò che viene aggiunto più tardi con StructTreeRoot.Append() / StructElement.MarkContent().
• Passa opts.title a AutoTag() — imposta anche /ViewerPreferences /DisplayDocTitle, che PDF/UA richiede accanto al titolo del documento.
• Un OutlineItem.Dest può puntare sia a una pagina esplicita sia a una destinazione denominata ({ name: '...' }) — usa le destinazioni denominate quando il numero di pagina di destinazione potrebbe variare al variare del contenuto.
• Verifica AddTOCResult.remainder quando l’auto-paginazione è disattivata — una casella del sommario troppo piccola per ogni voce smette silenziosamente di disegnare anziché traboccare la casella.

Problemi comuni

FAQ

Come aggiungere segnalibri a un PDF?

Crea un array di oggetti OutlineItem (Title, Dest, Children opzionale) e passalo a Document.SetOutlines().

Un sommario può estendersi su più pagine?

Sì — passa autoPaginate: true nelle opzioni di Page.AddTOC(), oppure verifica AddTOCResult.remainder e richiama AddTOC() su una nuova pagina per tutto ciò che non è stato inserito.

Come rendere un PDF accessibile (taggato)?

Chiama Document.AutoTag(), che inferisce intestazioni, paragrafi, tabelle e figure dal layout della pagina. Per contenuti aggiunti successivamente, o dove il risultato euristico necessita di correzione, usa direttamente StructTreeRoot.Append() e StructElement.MarkContent().

Qual è la differenza tra una destinazione basata sul numero di pagina e una destinazione nominata?

Una destinazione numerata (PageDest) fa riferimento a una pagina esplicita numerata a partire da 1. Una destinazione nominata (NamedDest) punta a un nome che il visualizzatore risolve tramite le tabelle di destinazioni nominate del documento — utile quando la pagina di destinazione può spostarsi.

Riepilogo API Reference

Vedi anche

• Aspose.PDF — Enterprise Documentation