Structure

Vue d’ensemble

Cette page couvre la navigation dans le document et la structure logique: les repères (signets), les tables des matières, les destinations nommées et l’arbre de structure balisé utilisé pour l’accessibilité et le réajustement.


Repères (Signets)

Document.GetOutlines() renvoie l’arbre de repères actuel en tant que OutlineItem[] ([] lorsqu’il n’y a pas de /Outlines); Document.SetOutlines() le remplace — passer [] supprime le repère entièrement. Chaque OutlineItem possède un Title, un Dest (un numéro de page ou une destination nommée), un Children optionnel pour l’imbrication, et un style (Color, Bold, Italic, Open).

const items: OutlineItem[] = sections.map((s) => {
  const item: OutlineItem = { Title: s.title, Dest: { name: s.dest } };
  if (s.subtype === 'sales') {
    item.Open = true;
    item.Children = ['Pasta', 'Pizza', 'Antipasti']
      .map((cat) => ({ Title: cat, Dest: { name: s.dest } }));
  }
  return item;
});
doc.SetOutlines(items);

Table des matières

Page.AddTOC() rend une liste d’objets TOCEntry — chacun avec un title et un numéro page cible — dans un rectangle sur une page, avec des titres retournés à la ligne, des points de suite et des étiquettes de page alignées à droite. Il renvoie un AddTOCResult indiquant combien d’entrées ont été dessinées et, lorsque la boîte est trop petite, le remainder qui n’a pas pu tenir.

page.AddTOC(
  sections.map((s, i) => ({ title: `${i + 1}. ${s.title}`, page: s.page.Number })),
  [72, 160, 400, 400],
  { font: 'Helvetica', fontSize: 13, rowGap: 18 },
);

Destinations nommées

Document.GetNamedDestinations() renvoie chaque destination nommée — en fusionnant l’arbre de noms /Names /Dests et le dictionnaire hérité /Dests — sous forme de paires { name, dest }, où dest est un PageDest ({ page, view }). Ce sont les mêmes cibles nommées qu’un OutlineItem.Dest ou une annotation de lien peut référencer par nom au lieu d’un numéro de page explicite.

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));
for (const { name, dest } of doc.GetNamedDestinations()) {
  console.log(name, '-> page', dest.page);
}

Arbre de Structure Étiquetée

Document.AutoTag() déduit et crée un /StructTreeRoot à partir de la mise en page — titres par regroupement de tailles de police, paragraphes par blocs de texte, tableaux par géométrie de repères, et décisions /Figure vs. /Artifact par image — et renvoie un AutoTagReport avec le nombre pour chaque type d’élément. Document.GetStructTree() relit le StructTreeRoot résultant, ou null lorsque le document n’est pas étiqueté.

const report = doc.AutoTag({ lang: 'en-US', title: 'Quarterly Report', tables: true });
console.log(report.headings, report.paragraphs, report.tables, report.figures);

const tree = doc.GetStructTree();
console.log(tree ? tree.GetText() : '(no structure tree)');

Le contenu ajouté après l’exécution de AutoTag() — une page remplie ultérieurement, par exemple — n’est pas couvert par ce passage et ne sera pas doublement étiqueté. StructTreeRoot.Append() et StructElement.MarkContent() sont les API d’édition manuelle aux côtés de l’approche heuristique : Append() ajoute un élément enfant d’un type donné, et MarkContent() marque une région de page comme appartenant à cet élément.


Conseils et Bonnes pratiques

  • Exécutez Document.AutoTag() une fois, après que le contenu de la page soit finalisé — il ne re-étiquette pas le contenu ajouté ultérieurement, donc étiquetez manuellement tout ce qui est ajouté plus tard avec StructTreeRoot.Append() / StructElement.MarkContent().
  • Passez opts.title à AutoTag() — cela définit également /ViewerPreferences /DisplayDocTitle, que PDF/UA exige en plus d’un titre de document.
  • Un OutlineItem.Dest peut cibler soit une page explicite, soit une destination nommée ({ name: '...' }) — utilisez les destinations nommées lorsque le numéro de page cible peut changer au fur et à mesure que le contenu évolue.
  • Vérifiez AddTOCResult.remainder lorsque la pagination automatique est désactivée — une boîte de table des matières trop petite pour chaque entrée cesse silencieusement de se dessiner plutôt que de déborder de la boîte.

Problèmes courants

ProblèmeCauseCorrection
Document.GetStructTree() renvoie nullLe document n’a pas été étiquetéAppelez Document.AutoTag() ou Document.CreateStructTree() d’abord
Le lien d’un élément du plan ne se résout pasSon Dest nomme une destination qui n’existe pas dans Document.GetNamedDestinations()Confirmez que la destination nommée existe, ou utilisez une page explicite Dest à la place
Page.AddTOC() s’arrête avant la dernière sectionLa cible rect est trop petite pour chaque entrée et autoPaginate est désactivéAgrandissez le rect, passez autoPaginate: true, ou gérez AddTOCResult.remainder
Le contenu ajouté après AutoTag() manque dans l’arbre de structureAutoTag() ne marque que le contenu présent lorsqu’il a été exécutéMarquez manuellement le contenu ultérieur avec StructTreeRoot.Append() / StructElement.MarkContent()

FAQ

Comment ajouter des signets à un PDF?

Créez un tableau d’objets OutlineItem (Title, Dest, Children optionnel) et transmettez-le à Document.SetOutlines().

Une table des matières peut-elle s’étendre sur plusieurs pages?

Oui — transmettez autoPaginate: true dans les options de Page.AddTOC(), ou vérifiez AddTOCResult.remainder et appelez AddTOC() de nouveau sur une nouvelle page pour tout ce qui n’a pas tenu.

Comment rendre un PDF accessible (balisé)?

Appelez Document.AutoTag(), qui déduit les titres, paragraphes, tableaux et figures à partir de la mise en page. Pour le contenu ajouté ultérieurement, ou lorsque le résultat heuristique doit être corrigé, utilisez directement StructTreeRoot.Append() et StructElement.MarkContent().

Quelle est la différence entre une destination par numéro de page et une destination nommée ?

Une destination par numéro de page (PageDest) cible une page explicite numérotée à partir de 1. Une destination nommée (NamedDest) cible un nom que le lecteur résout via les tables de destinations nommées du document — utile lorsque la page cible peut se déplacer.


API Reference Résumé

Classe/MéthodeDescription
Document.GetOutlines() / Document.SetOutlines()Lire ou remplacer l’arborescence du plan du document (signet)
OutlineItemUn nœud d’arborescence : Title, Dest, optionnel Children
Page.AddTOC()Rendre une table des matières dans un rectangle de page
TOCEntry / AddTOCResultLes données d’une ligne de TOC, et le résultat de son rendu
Document.GetNamedDestinations()Listez chaque destination nommée dans le document
Document.AutoTag()Déduisez et créez un arbre de structure balisé à partir de la mise en page
Document.GetStructTree() / Document.CreateStructTree()Lire ou créer le StructTreeRoot du document
StructTreeRoot.Append() / StructElement.Append() / StructElement.MarkContent()Rédiger ou étendre manuellement l’arbre de structure

Voir aussi

 Français