Hoe werk je met PDF-structuur in TypeScript

Deze gids laat zien hoe je documentnavigatie en logische structuur in PDF-bestanden bouwt met Aspose.PDF FOSS voor TypeScript: een klikbare inhoudsopgave op een pagina, een bladwijzeroverzicht op documentniveau, benoemde bestemmingen, en een getagde structuurboom voor toegankelijkheid. Het vereist Node.js 22 of hoger.

Stapsgewijze handleiding

Stap 1: Installeer het pakket

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

Verifieer de installatie door de Document klasse te importeren in een nieuw TypeScript bestand — deze regel zou zonder fout moeten slagen zodra het pakket geïnstalleerd is:

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

Stap 2: Importeer vereiste klassen

Importeer Document om het bestand te openen en OutlineItem voor de bladwijzervermeldingen die in Stap 4 zijn gemaakt:

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

Stap 3: Voeg een inhoudsopgave toe

Page.AddTOC() neemt een array van { title, page } vermeldingen, een begrenzende rect, en stijlopties; het tekent gestippelde leidraden en klikbare links naar de doelpagina’s:

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

Stap 4: Voeg bladwijzers toe

Document.SetOutlines() vervangt het bladwijzervenster van het document door een array van OutlineItem objecten. Elk item kan een Dest (paginadoel) bevatten, opmaak (Color, Bold), en geneste Children voor een inklapbare boom:

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

Stap 5: Lees contouren en benoemde bestemmingen

Document.GetOutlines() retourneert de huidige bladwijzerboom. Document.GetNamedDestinations() retourneert elke benoemde bestemming die op het document is geregistreerd — handig om te verifiëren dat elk contourdoel en elke TOC-link daadwerkelijk naar een echte pagina leidt:

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

Stap 6: Bouw een getagde structuurboom

Document.GetStructTree() retourneert de bestaande structuurboom (of null als het document nog niet is getagd). StructTreeRoot.Append(tag) voegt een kindelement toe, zoals 'H2' of 'P', en retourneert een StructElement, en StructElement.MarkContent(page, quad) koppelt dat element aan de paginainhoud die het beschrijft:

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

Veelvoorkomende problemen en oplossingen

Document.GetStructTree() returns null. Het document is nog niet getagd — roep Document.CreateStructTree() (of Document.AutoTag()) vóór handmatig opstellen van elementen met StructTreeRoot.Append() / StructElement.MarkContent().

Een outline-item springt niet naar de juiste pagina. OutlineItem.Dest moet een bestemming opgeven die daadwerkelijk bestaat — controleer item.Dest.name against Document.GetNamedDestinations() voordat je opslaat, zoals weergegeven in Stap 5.

Page.AddTOC() vermeldingen wijzen naar de verkeerde pagina. page in elk TOC-item is het paginanummer van de doelpagina zelf — bevestig dit met page.Number op het daadwerkelijke doel Page, niet een veronderstelde array-index.

Bladwijzers verdwijnen na een latere Document.SetOutlines() aanroep. SetOutlines() vervangt de volledige bladwijzerboom — lees de huidige boom met Document.GetOutlines() eerst, wijzig de array, vervolgens geef de hele array terug als bladwijzers worden toegevoegd in plaats van vervangen.

Veelgestelde vragen

Kan een bladwijzer al uitgeklapt geopend worden?

Ja — stel Open: true in op de OutlineItem om de kinderen van dat knooppunt standaard zichtbaar te maken in het bladwijzervenster.

Wat is het verschil tussen een bladwijzer en een benoemde bestemming?

Een bladwijzer (OutlineItem) is een zichtbare invoer in het navigatiepaneel; een benoemde bestemming (Document.GetNamedDestinations() / SetNamedDestination()) is een interne, herbruikbare paginatarget waar een bladwijzer, een inhoudsopgave-item of een link-annotatie allemaal naar kan verwijzen via de naam.

Heeft het taggen van een document invloed op hoe het eruitziet?

Nee — een structuurboom (StructTreeRoot, StructElement) is een parallelle logische laag die de leesvolgorde en semantiek beschrijft; hij verandert de zichtbare inhoud van de pagina niet.

Kan ik bladwijzers nesten?

Ja — stel Children in op een OutlineItem als een array van verdere OutlineItem-objecten om een inklapbare, meerlagige boom te bouwen.