Cum să lucrezi cu structura PDF în TypeScript

Acest ghid arată cum să construiești navigarea documentului și structura logică în fișiere PDF cu Aspose.PDF FOSS pentru TypeScript: un cuprins clicabil pe o pagină, un contur de marcaje la nivel de document, destinații denumite și un arbore de structură etichetat pentru accesibilitate. Necesită Node.js 22 sau o versiune ulterioară.

Ghid pas cu pas

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

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

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

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

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

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

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

Probleme comune și soluții

Document.GetStructTree() returns null. Documentul nu a fost încă etichetat — apelați Document.CreateStructTree() (sau Document.AutoTag()) înainte de a crea manual elemente cu StructTreeRoot.Append() / StructElement.MarkContent().

Un element din schiță nu sare la pagina corectă. OutlineItem.Dest trebuie să denumească o destinație care există cu adevărat — verificați încrucișat item.Dest.name against Document.GetNamedDestinations() înainte de salvare, așa cum se arată în Pasul 5.

Page.AddTOC() intrările indică pagina greșită. page în fiecare intrare din Cuprins este numărul paginii țintă — confirmați-l față de page.Number pe ținta reală Page, nu un index de tablou presupus.

Semnele de carte dispar după un moment ulterior Document.SetOutlines() apel. SetOutlines() înlocuiește întregul arbore de semne de carte — citește arborele curent cu Document.GetOutlines() mai întâi, modifică tabloul, apoi transmite întregul tablou înapoi dacă semnele de carte sunt adăugate în loc să fie înlocuite.

Întrebări frecvente

Poate un semn de carte să se deschidă deja extins?

Da — setează Open: true pe OutlineItem pentru ca copiii acelui nod să fie vizibili implicit în panoul de semne de carte.

Care este diferența dintre un semn de carte și o destinație numită?

Un semn de carte (OutlineItem) este o intrare vizibilă în panoul de navigare; o destinație numită (Document.GetNamedDestinations() / SetNamedDestination()) este o țintă de pagină internă, reutilizabilă, la care poate să se refere un semn de carte, o intrare din Cuprins (TOC) sau o adnotare de tip link, prin nume.

Etichetarea unui document afectează aspectul său?

Nu — un arbore de structură (StructTreeRoot, StructElement) este un strat logic paralel care descrie ordinea de lectură și semantica; nu modifică conținutul vizibil al paginii.

Pot să imbric semne de carte?

Da — setează Children pe un OutlineItem la un tablou de obiecte OutlineItem suplimentare pentru a construi un arbore pliabil, cu mai multe niveluri.

Vezi și:

• Core API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base