Comment travailler avec la structure PDF en TypeScript

Ce guide montre comment créer une navigation de document et une structure logique dans les fichiers PDF avec Aspose.PDF FOSS pour TypeScript: une table des matières cliquable sur une page, un plan de signets au niveau du document, des destinations nommées et un arbre de structure balisé pour l’accessibilité. Il nécessite Node.js 22 ou une version ultérieure.

Guide étape par étape

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

Problèmes courants et solutions

Document.GetStructTree() returns null. Le document n’a pas encore été étiqueté — appelez Document.CreateStructTree() (ou Document.AutoTag()) avant de créer manuellement des éléments avec StructTreeRoot.Append() / StructElement.MarkContent().

Un élément de plan ne saute pas à la bonne page. OutlineItem.Dest doit nommer une destination qui existe réellement — vérifiez item.Dest.name against Document.GetNamedDestinations() avant d’enregistrer, comme indiqué à l’étape 5.

Page.AddTOC() les entrées pointent vers la mauvaise page. page dans chaque entrée de TOC, le numéro de page propre à la page cible — confirmez-le avec page.Number sur la cible réelle Page, pas un indice de tableau supposé.

Les signets disparaissent après un appel ultérieur Document.SetOutlines() appel. SetOutlines() remplace l’arbre complet des signets — lisez l’arbre actuel avec Document.GetOutlines() d’abord, modifiez le tableau, puis renvoyez le tableau complet si des signets sont ajoutés plutôt que remplacés.

Foire aux questions

Un signet peut-il s’ouvrir déjà déplié?

Oui — définissez Open: true sur le OutlineItem pour que les enfants de ce nœud soient visibles par défaut dans le panneau des signets.

Quelle est la différence entre un signet et une destination nommée?

Un signet (OutlineItem) est une entrée visible dans le panneau de navigation; une destination nommée (Document.GetNamedDestinations() / SetNamedDestination()) est une cible de page interne et réutilisable vers laquelle un signet, une entrée de table des matières ou une annotation de lien peuvent tous pointer par son nom.

L’étiquetage d’un document affecte-t-il son apparence?

Non — un arbre de structure (StructTreeRoot, StructElement) est une couche logique parallèle décrivant l’ordre de lecture et la sémantique; il ne modifie pas le contenu visible de la page.

Puis-je imbriquer des signets?

Oui — définissez Children sur un OutlineItem avec un tableau d’objets OutlineItem supplémentaires pour créer un arbre pliable à plusieurs niveaux.

Voir aussi

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