Come lavorare con la struttura PDF in TypeScript

Questa guida mostra come creare la navigazione del documento e la struttura logica nei file PDF con Aspose.PDF FOSS per TypeScript: un indice cliccabile su una pagina, un sommario di segnalibri a livello di documento, destinazioni nominate e un albero di struttura taggato per l’accessibilità. Richiede Node.js 22 o versioni successive.

Guida passo-passo

Passo 1: Installa il pacchetto

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta che il pacchetto è stato installato:

import { Document } from '@asposefoss/pdf';

Passo 2: Importa le classi richieste

Importa Document per aprire il file e OutlineItem per le voci dei segnalibri create nello Step 4:

import { Document, OutlineItem } from '@asposefoss/pdf';

Step 3: Aggiungi un indice

Page.AddTOC() accetta un array di voci { title, page }, un rect di delimitazione e opzioni di stile; disegna guide puntinate e collegamenti cliccabili alle pagine di destinazione:

const page = doc.Pages[0];

page.AddTOC(
  [
    { title: '1.  Introduction', page: 2 },
    { title: '2.  Methodology', page: 5 },
    { title: '3.  Results', page: 9 },
  ],
  [72, 160, 400, 600],
  { font: 'Helvetica', fontSize: 13, color: [0.1, 0.1, 0.15], rowGap: 18 },
);

Step 4: Aggiungi segnalibri

Document.SetOutlines() sostituisce il pannello dei segnalibri del documento con un array di oggetti OutlineItem. Ogni elemento può contenere un Dest (destinazione della pagina), stile (Color, Bold) e un Children annidato per una struttura a scomparsa:

const items: OutlineItem[] = [
  { Title: 'Sales', Dest: { name: 'section.sales' }, Open: true, Color: [0.1, 0.4, 0.1] },
  { Title: 'Appendix', Dest: { name: 'section.appendix' } },
];

doc.SetOutlines(items);

Step 5: Leggi gli schemi e le destinazioni nominate

Document.GetOutlines() restituisce l’albero dei segnalibri attuale. Document.GetNamedDestinations() restituisce ogni destinazione nominata registrata nel documento — utile per verificare che ogni obiettivo dello schema e ogni collegamento dell’indice risolvano effettivamente in una pagina reale:

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));

const walk = (nodes: OutlineItem[]): void => {
  for (const item of nodes) {
    if (item.Dest && 'name' in item.Dest) {
      console.log(destNames.has(item.Dest.name), item.Title);
    }
    if (item.Children) walk(item.Children);
  }
};
walk(doc.GetOutlines());

Step 6: Costruisci una gerarchia di tag

Document.GetStructTree() restituisce l’albero della struttura esistente (o null se il documento non è stato etichettato). StructTreeRoot.Append(tag) aggiunge un elemento figlio come 'H2' o 'P' e restituisce un StructElement, e StructElement.MarkContent(page, quad) associa quell’elemento al contenuto della pagina che descrive:

function tagPage(doc: Document, page: Page, headingText: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('tagPage: the document is not tagged yet');

  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(headingText) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

Problemi comuni e soluzioni

Document.GetStructTree() returns null. Il documento non è ancora stato taggato — chiama Document.CreateStructTree() (o Document.AutoTag()) prima di creare manualmente gli elementi con StructTreeRoot.Append() / StructElement.MarkContent().

Una voce dell’indice non salta alla pagina corretta. OutlineItem.Dest deve indicare una destinazione che esiste davvero — verifica incrociata item.Dest.name against Document.GetNamedDestinations() prima di salvare, come mostrato nel Passo 5.

Page.AddTOC() le voci puntano alla pagina sbagliata. page in ogni voce dell’Indice è il numero di pagina della pagina di destinazione — confrontalo con page.Number sul target reale Page, non un indice di array presunto.

I segnalibri scompaiono dopo un successivo Document.SetOutlines() chiamata. SetOutlines() sostituisce l’intero albero dei segnalibri — leggi l’albero corrente con Document.GetOutlines() prima, modifica l’array, quindi restituisci l’intero array se i segnalibri vengono aggiunti anziché sostituiti.

Domande frequenti

Un segnalibro può aprirsi già espanso?

Sì — imposta Open: true su OutlineItem per far sì che i figli di quel nodo siano visibili per impostazione predefinita nel pannello dei segnalibri.

Qual è la differenza tra un segnalibro e una destinazione nominata?

Un segnalibro (OutlineItem) è una voce visibile nel pannello di navigazione; una destinazione nominata (Document.GetNamedDestinations() / SetNamedDestination()) è un target di pagina interno e riutilizzabile a cui un segnalibro, una voce di TOC o un’annotazione di collegamento possono tutti puntare per nome.

L’etichettatura di un documento influisce sul suo aspetto?

No — un albero strutturale (StructTreeRoot, StructElement) è un livello logico parallelo che descrive l’ordine di lettura e la semantica; non modifica il contenuto visibile della pagina.

Posso nidificare i segnalibri?

Sì — imposta Children su un OutlineItem a un array di ulteriori oggetti OutlineItem per costruire un albero a più livelli, collassabile.