Hur man arbetar med PDF-struktur i TypeScript

Den här guiden visar hur man bygger dokumentnavigering och logisk struktur i PDF-filer med Aspose.PDF FOSS för TypeScript: en klickbar innehållsförteckning på en sida, en bokmärkesöversikt på dokumentnivå, namngivna destinationer och ett taggat strukturtträd för tillgänglighet. Det kräver Node.js 22 eller senare.

Steg-för-steg-guide

Steg 1: Installera paketet

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

Verifiera installationen genom att importera Document-klassen i en ny TypeScript-fil — den här raden bör lösa utan fel när paketet är installerat:

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

Steg 2: Importera erforderliga klasser

Importera Document för att öppna filen och OutlineItem för bokmärkesposterna som byggdes i steg 4:

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

Steg 3: Lägg till en innehållsförteckning

Page.AddTOC() tar emot en array av { title, page }-poster, en begränsande rect och stilalternativ; den ritar prickade ledare och klickbara länkar till målsidorna:

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

Steg 4: Lägg till bokmärken

Document.SetOutlines() ersätter dokumentets bokmärkespanel med en array av OutlineItem-objekt. Varje objekt kan innehålla en Dest (sidestination), stil (Color, Bold) och nästlad Children för ett kollapsbart träd:

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

Steg 5: Läs avsnitt och namngivna destinationer

Document.GetOutlines() returnerar det aktuella bokmärkesträdet. Document.GetNamedDestinations() returnerar varje namngiven destination som är registrerad i dokumentet — användbart för att verifiera att varje outline-mål och TOC-länk faktiskt pekar på en verklig sida:

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

Steg 6: Bygg ett taggat strukturräd

Document.GetStructTree() returnerar det befintliga strukturträdet (eller null om dokumentet inte har taggats). StructTreeRoot.Append(tag) lägger till ett underordnat element såsom 'H2' eller 'P' och returnerar en StructElement, och StructElement.MarkContent(page, quad) associerar det elementet med sidans innehåll som det beskriver:

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

Vanliga problem och lösningar

Document.GetStructTree() returns null. Dokumentet har ännu inte taggats — ring Document.CreateStructTree() (eller Document.AutoTag()) innan hand-authoring-element med StructTreeRoot.Append() / StructElement.MarkContent().

En dispositionspunkt hoppar inte till rätt sida. OutlineItem.Dest måste ange en destination som faktiskt finns — dubbelkolla item.Dest.name against Document.GetNamedDestinations() innan du sparar, som visas i steg 5.

Page.AddTOC() poster pekar på fel sida. page i varje innehållsförteckningspost är mål sidans eget sidnummer — bekräfta det mot page.Number på det faktiska målet Page, inte ett antaget arrayindex.

Bokmärken försvinner efter ett senare Document.SetOutlines() anrop. SetOutlines() ersätter hela bokmärkensträdet — läs det aktuella trädet med Document.GetOutlines() först, modifiera arrayen, sedan skicka tillbaka hela arrayen om bokmärken läggs till snarare än ersätts.

Vanliga frågor

Kan ett bokmärke öppnas redan expanderat?

Ja — sätt Open: true på OutlineItem för att ha den nodens barn synliga som standard i bokmärkespanelen.

Vad är skillnaden mellan ett bokmärke och en namngiven destination?

Ett bokmärke (OutlineItem) är en synlig post i navigationspanelen; en namngiven destination (Document.GetNamedDestinations() / SetNamedDestination()) är ett internt, återanvändbart sidmål som ett bokmärke, en innehållsförteckningspost eller en länkanotering kan peka på med namn.

Påverkar taggning av ett dokument hur det ser ut?

Nej — ett strukturträd (StructTreeRoot, StructElement) är ett parallellt logiskt lager som beskriver läsordning och semantik; det ändrar inte sidans synliga innehåll.

Kan jag nästla bokmärken?

Ja — sätt Children på en OutlineItem till en array av ytterligare OutlineItem-objekt för att bygga ett hopfällbart, flernivåträd.