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 avecStructTreeRoot.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.Destpeut 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.remainderlorsque 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ème | Cause | Correction |
|---|---|---|
Document.GetStructTree() renvoie null | Le 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 pas | Son 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 section | La 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 structure | AutoTag() 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éthode | Description |
|---|---|
Document.GetOutlines() / Document.SetOutlines() | Lire ou remplacer l’arborescence du plan du document (signet) |
OutlineItem | Un nœud d’arborescence : Title, Dest, optionnel Children |
Page.AddTOC() | Rendre une table des matières dans un rectangle de page |
TOCEntry / AddTOCResult | Les 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 |