Travailler avec les champs d’index et de tables

Travailler avec les champs Index et Tables

Ce guide montre comment travailler avec la famille de champs «Index and Tables» de Word — les champs derrière une table des matières, un index, une table des figures et une table des autorités. Chacun de ceux-ci est une sous-classe Field dans l’espace de noms Aspose.Words.Fields: FieldToc (table des matières ou des figures), FieldIndex (index), FieldXE (entrée d’index), FieldToa (table des autorités), FieldTA (entrée de table des autorités, ou citation), FieldTC (entrée de table des matières), et FieldRD (document référencé, pour construire un index ou une table des matières combinés à travers plusieurs fichiers).

Classe de base du champ

Chaque classe de champ de cette famille hérite de Field, qui expose Start, Separator et End (les nœuds FieldStart, FieldSeparator et FieldEnd qui délimitent le champ dans le flux d’exécution), Type (une valeur FieldType — FieldTOC, FieldIndex, FieldTOA, FieldTOCEntry, FieldIndexEntry, FieldTOAEntry ou FieldRefDoc pour cette famille), Result/DisplayResult (le texte actuellement calculé du champ), IsLocked et IsDirty, ainsi que les méthodes GetFieldCode(), Update(), Unlink() et Remove(). Update() recompute le résultat du champ; pour une table des matières, cela signifie reconstruire la liste des entrées à partir des titres du document ou des marqueurs FieldTC.

Insertion d’une table des matières

DocumentBuilder.InsertTableOfContents(switches) insère un(e) FieldToc à la position actuelle du constructeur, en utilisant une chaîne d’interrupteurs de champ Word (par exemple "\o \"1-3\" \h \z \u") pour contrôler quels niveaux de titres sont inclus et comment le résultat est formaté — les mêmes interrupteurs que Word écrit lorsqu’on insère une table des matières via l’interface. Une fois inséré, FieldToc.UpdatePageNumbers() recompute la partie numéro de page des entrées existantes. FieldToc expose également les propriétés contrôlant directement la structure de la table des matières: HeadingLevelRange et EntryLevelRange (quels niveaux de plan sont inclus), EntryIdentifier (l’identifiant du champ TC que la table des matières doit collecter, pour créer plusieurs tables des matières à partir de différents marqueurs FieldTC), InsertHyperlinks, PreserveTabs/PreserveLineBreaks, EntrySeparator/SequenceSeparator, BookmarkName, et — pour une table des figures plutôt qu’une table des matières — TableOfFiguresLabel et CaptionlessTableOfFiguresLabel.

Marquage d’entrées personnalisées de table des matières

Toutes les entrées du TOC ne proviennent pas d’un style de titre. FieldTC marque un emplacement spécifique comme entrée de table des matières indépendante du style de paragraphe: FieldTC.Text est le texte de l’entrée, EntryLevel est le niveau de plan auquel elle doit apparaître, TypeIdentifier la relie à un FieldToc.EntryIdentifier lors de la création de plusieurs tables des matières, et OmitPageNumber supprime le numéro de page pour cette entrée.

Créer un index

FieldIndex implémente le champ INDEX, qui compile les marqueurs FieldXE (entrée d’index) d’un document en un index alphabétique. FieldXE.Text est le texte de l’entrée, EntryType regroupe les entrées en sous-niveaux à l’aide d’une syntaxe séparée par des deux-points, PageRangeBookmarkName marque un signet dont l’étendue devient une plage de pages dans l’index plutôt qu’un numéro de page unique, et IsBold/IsItalic formatent la référence de page résultante. Du côté FieldIndex, Heading insère des séparateurs de lettres d’en-tête (A, B, C…), LetterRange limite l’index à un sous-ensemble de l’alphabet, RunSubentriesOnSameLine contrôle la mise en page des sous-entrées, et PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator contrôlent la ponctuation entre une entrée et sa référence de page. FieldIndexFormat énumère séparément les styles visuels d’index intégrés de Word (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).

Table des autorités

FieldToa et FieldTA sont l’équivalent des autorités de FieldIndex/FieldXE: FieldTA marque une citation dans le texte (LongCitation et ShortCitation texte, EntryCategory pour la regrouper sous un titre tel que «Cases» ou «Statutes», et IsBold/IsItalic pour le formatage), et FieldToa compile ces citations dans un tableau, EntryCategory sélectionnant la catégorie à compiler, UseHeading et UsePassim contrôlant les en-têtes de catégorie et la convention «passim» pour les sources citées de nombreuses fois, et PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting contrôlant la mise en page.

Faire référence à du contenu provenant d’autres documents

FieldRD implémente le champ RD, qui indique à un champ de TOC, d’index ou de table des autorités d’inclure des entrées provenant d’un autre fichier lors de la compilation — FieldRD.FileName est le document référencé, et IsPathRelative contrôle si ce chemin est résolu relativement au document actuel.

Conseils et meilleures pratiques

• Construisez la chaîne d’options de la table des matières de la même manière que Word le fait (\o "1-3" \h \z \u) plutôt que de configurer chaque propriété FieldToc individuellement, puis ajustez uniquement les propriétés spécifiques que vous devez modifier par la suite.
• Appelez FieldToc.UpdatePageNumbers() (ou Field.Update()) après les modifications de contenu afin qu’une table des matières, un index ou une table des autorités reflète le document actuel plutôt que des résultats obsolètes datant de son insertion.
• Utilisez FieldTC.TypeIdentifier conjointement avec FieldToc.EntryIdentifier lorsqu’un document nécessite plus d’une table des matières (par exemple une table des matières principale et une table des figures distincte) construite à partir de différents ensembles d’entrées.
• Définissez FieldXE.PageRangeBookmarkName (ou le marquage de plage équivalent de FieldTA) plutôt que de formater manuellement une plage de pages dans le texte de l’entrée, afin que l’index ou la table reste cohérent(e) si le contenu se déplace.
• Rappelez-vous que les numéros de page dans les résultats INDEX/TOC/TOA de cette édition sont évalués à des valeurs de substitution plutôt qu’à de vrais numéros de page, car la mise en page et la pagination ne font pas partie de cette édition.

Problèmes courants

FAQ

Comment insérer une table des matières de manière programmatique?

Appelez DocumentBuilder.InsertTableOfContents(switches) avec une chaîne d’options de type Word, telle que "\o \"1-3\" \h \z \u", à l’endroit où la table des matières doit apparaître.

Comment marquer du texte comme entrée d’index?

Insérez un champ FieldXE à cet emplacement (par exemple via DocumentBuilder.InsertField) avec sa propriété Text définie sur le texte de l’entrée; FieldIndex compile tous les marqueurs FieldXE du document dans le résultat de l’index.

Quelle est la différence entre FieldTC et les entrées de table des matières basées sur les titres?

Le comportement par défaut de la table des matières de Word collecte les entrées à partir des paragraphes utilisant les styles de titre. FieldTC vous permet de marquer un emplacement arbitraire comme entrée de table des matières, indépendamment du style de paragraphe, ce que FieldToc peut inclure via des valeurs correspondantes EntryIdentifier/TypeIdentifier.

Comment rafraîchir une table des matières ou un index après que le document a changé?

Appelez Update() sur le champ spécifique (par exemple FieldToc.Update(), ou FieldToc.UpdatePageNumbers() pour les numéros de page uniquement), ou Document.UpdateFields() pour rafraîchir tous les champs du document.

Puis-je compiler une table des matières ou un index à travers plusieurs documents?

Oui — insérez un champ FieldRD pointant vers chaque document supplémentaire via FileName; le champ de compilation (FieldToc, FieldIndex ou FieldToa) inclut les entrées des documents référencés lorsqu’il est mis à jour.

Résumé API Reference

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation