Hogyan dolgozzunk a PDF struktúrával TypeScriptben

Ez az útmutató bemutatja, hogyan építsünk dokumentumnavigációt és logikai struktúrát PDF-fájlokban a Aspose.PDF FOSS megoldással a TypeScript számára: kattintható tartalomjegyzék egy oldalon, dokumentumszintű könyvjelzővázlat, elnevezett célpontok, valamint egy címkézett struktúrafas fa a hozzáférhetőség érdekében. Node.js 22 vagy újabb verzió szükséges.

Lépésről lépésre útmutató

1. lépés: A csomag telepítése

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

Ellenőrizze a telepítést a Document osztály importálásával egy új TypeScript fájlban — ennek a sornak hibamentesen kell lefutnia, miután a csomag telepítve van:

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

2. lépés: A szükséges osztályok importálása

Importálja a Document elemet a fájl megnyitásához, és a OutlineItem elemet a 4. lépésben létrehozott könyvjelző bejegyzésekhez:

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

3. lépés: Tartalomjegyzék hozzáadása

Page.AddTOC() egy { title, page } bejegyzésekből álló tömböt, egy határoló rect-t és stílusbeállításokat fogad; pontozott vezetővonalakat és kattintható hivatkozásokat rajzol a céloldalakra:

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

4. lépés: Könyvjelzők hozzáadása

Document.SetOutlines() kicseréli a dokumentum könyvjelző paneljét egy OutlineItem objektumokból álló tömbre. Minden elem tartalmazhat egy Dest-t (oldalcél), stílusbeállításokat (Color, Bold), és beágyazott Children-t egy összehajtható fa számára:

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

5. lépés: Vázlatok és névvel ellátott célpontok olvasása

Document.GetOutlines() visszaadja a jelenlegi könyvjelzőfát. Document.GetNamedDestinations() visszaadja a dokumentumban regisztrált összes névvel ellátott célpontot — hasznos annak ellenőrzésére, hogy minden vázlati cél és a tartalomjegyzék hivatkozása valóban egy valós oldalra mutat-e:

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

6. lépés: Címkézett szerkezeti fa felépítése

Document.GetStructTree() visszaadja a meglévő struktúrafát (vagy null, ha a dokumentum még nincs címkézve). StructTreeRoot.Append(tag) egy gyermekelemet ad hozzá, például 'H2' vagy 'P', és visszaad egy StructElement-t, míg StructElement.MarkContent(page, quad) összekapcsolja azt az elem a leírt oldal tartalmával:

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

Általános problémák és megoldások

Document.GetStructTree() returns null. A dokumentum még nincs címkézve — hívja Document.CreateStructTree() (vagy Document.AutoTag()) mielőtt kézzel szerkesztené az elemeket a StructTreeRoot.Append() / StructElement.MarkContent().

A vázlat eleme nem ugrik a megfelelő oldalra. OutlineItem.Dest meg kell neveznie egy ténylegesen létező célt — ellenőrizze item.Dest.name against Document.GetNamedDestinations() mentés előtt, ahogy az 5. lépésben látható.

Page.AddTOC() a bejegyzések a rossz oldalra mutatnak. page az egyes TOC bejegyzésekben a céllap saját oldalszáma — erősítse meg ezzel szemben page.Number a tényleges célen Page, nem egy feltételezett tömbindex.

Könyvjelzők eltűnnek egy későbbi Document.SetOutlines() hívás. SetOutlines() lecseréli az egész könyvjelzőfát — olvassa be a jelenlegi fát a Document.GetOutlines() először, módosítsa a tömböt, majd adja vissza a teljes tömböt, ha a könyvjelzőket hozzáadják ahelyett, hogy lecserélnék.

Gyakran Ismételt Kérdések

Megnyithat egy könyvjelző már kibontott állapotban?

Igen — állítsd be a Open: true értékét a OutlineItem elemre, hogy az adott csomópont gyerekei alapértelmezés szerint láthatóak legyenek a könyvjelző panelen.

Mi a különbség egy könyvjelző és egy nevezett cél között?

A könyvjelző (OutlineItem) egy látható bejegyzés a navigációs panelen; egy nevezett cél (Document.GetNamedDestinations() / SetNamedDestination()) egy belső, újrahasználható oldalcél, amelyre egy könyvjelző, egy TOC-bejegyzés vagy egy link-annotáció is hivatkozhat név szerint.

A dokumentum címkézése befolyásolja a megjelenését?

Nem — a struktúrafa (StructTreeRoot, StructElement) egy párhuzamos logikai réteg, amely leírja az olvasási sorrendet és a szemantikai rétegeket; nem változtatja meg az oldal látható tartalmát.

Beágyazhatok könyvjelzőket?

Igen — állítsd be a Children értékét egy OutlineItem elemnél egy további OutlineItem objektumokat tartalmazó tömbre, hogy összehajtható, több szintű fát építs.