Ajouter une table des matières à un document Word en Java

Créer une table des matières navigable est essentiel lors de la création de gros rapports Word ou de manuels que les utilisateurs doivent parcourir rapidement. Conholdate.Total for Java fournit un SDK robuste qui simplifie le travail avec les fichiers DOCX directement depuis les applications Java. Dans ce guide étape par étape, vous apprendrez comment ajouter une table des matières à un document Word en Java, en couvrant la configuration, l’explication du code et les meilleures pratiques.

Exemple complet fonctionnel d’ajout d’une table des matières à un document Word en Java

L’exemple suivant montre comment insérer une table des matières dans un fichier DOCX à l’aide de Conholdate.Total for Java.

import com.aspose.words.Document;
import com.aspose.words.DocumentBuilder;
import com.aspose.words.BreakType;
import com.aspose.words.StyleIdentifier;

public class AddTableOfContentsExample {
    public static void main(String[] args) throws Exception {
        // Directory where the output document will be saved
        String dataDir = "output/";

// Create a new document and a builder to work with it
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table of contents field at the current cursor position.
        // "\o \"1-3\" \h \z \u" includes heading levels 1-3, makes entries
        // clickable hyperlinks, hides tab leaders in Web layout, and uses
        // outline levels applied to non-heading styles.
        builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

// Start the actual document content on the second page.
        builder.insertBreak(BreakType.PAGE_BREAK);

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("Heading 1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 1.1");
        builder.writeln("Heading 1.2");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("Heading 2");
        builder.writeln("Heading 3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 3.1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
        builder.writeln("Heading 3.1.1");
        builder.writeln("Heading 3.1.2");
        builder.writeln("Heading 3.1.3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        builder.writeln("Heading 3.2");
        builder.writeln("Heading 3.3");

// The newly inserted table of contents is initially empty.
        // It needs to be populated by updating the fields in the document.
        doc.updateFields();

doc.save(dataDir + "TableOfContents.docx");
    }
}

Remarque : Cet exemple de code démontre la fonctionnalité principale. Avant de l’utiliser dans votre projet, assurez-vous de mettre à jour le répertoire de sortie (dataDir) pour qu’il corresponde à l’emplacement réel de votre fichier, vérifiez que toutes les dépendances requises sont correctement installées et testez soigneusement dans votre environnement de développement. Si vous rencontrez des problèmes, veuillez consulter la documentation officielle ou contacter l’équipe de support pour obtenir de l’aide.

Comprendre l’ajout de la table des matières à un document Word en code Java

Voici une répartition des principales étapes exécutées par le code d’exemple :

Créer le document et un constructeur - Document représente le fichier Word en mémoire, et DocumentBuilder vous fournit des méthodes pour insérer du contenu et des champs.
```
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
```
Insérer le champ de table des matières - insertTableOfContents écrit un champ de table des matières à la position du curseur. La chaîne d’options contrôle son comportement : \o "1-3" inclut les niveaux de titres 1 à 3, \h rend les entrées des hyperliens cliquables, \z masque les tirets de tabulation et les numéros de page en mode d’affichage Web, et \u utilise le niveau de plan appliqué aux paragraphes.
```
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");
```
Commencer le contenu sur une nouvelle page - insertBreak(BreakType.PAGE_BREAK) place le corps réel du document sur la page après la table des matières, ainsi la table des matières possède sa propre page.
```
builder.insertBreak(BreakType.PAGE_BREAK);
```
Ajouter du contenu avec style de titre - Définir setStyleIdentifier sur le format de paragraphe du builder à HEADING_1, HEADING_2 ou HEADING_3 avant d’appeler writeln crée des paragraphes stylisés avec le style de titre intégré correspondant, que le champ TOC parcourt pour détecter les entrées.

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
builder.writeln("Heading 1");

Une référence API détaillée est disponible sur la page API Reference.

Mettre à jour les champs et enregistrer - doc.updateFields() remplit la table des matières avec les entrées et les numéros de page maintenant que les titres existent, et doc.save écrit le document sur le disque.

doc.updateFields();
doc.save(dataDir + "TableOfContents.docx");

Installation et configuration de Conholdate.Total pour Java

Ajoutez le référentiel Maven de Conholdate et la dépendance SDK à votre pom.xml :

<repositories>
    <repository>
        <id>conholdate-repo</id>
        <name>Conholdate Maven Repository</name>
        <url>https://repository.conholdate.com/repo/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.conholdate</groupId>
    <artifactId>conholdate-total</artifactId>
    <version>24.9</version>
    <type>pom</type>
</dependency>

Téléchargez le dernier package SDK depuis la page de téléchargement. Le SDK nécessite Java 8 ou une version supérieure et fonctionne sur n’importe quelle JVM standard. Aucun composant d’exécution supplémentaire n’est requis.

Meilleures pratiques pour générer une table des matières Word avec Java

Utiliser des styles de titres cohérents - Le TOC récupère les paragraphes formatés avec les niveaux de titres intégrés (Titre 1, Titre 2, etc.). Assurez‑vous que votre document source utilise ces styles pour une génération fiable des entrées.
Limiter la profondeur des titres - Inclure trop de niveaux peut rendre le TOC difficile à gérer. Les rapports typiques utilisent les niveaux 1‑3, comme le montre le commutateur \o "1-3" de l’exemple.
Activer les hyperliens - Inclure le commutateur \h crée des entrées cliquables, améliorant la navigation dans le document final.
Toujours appeler updateFields après l’insertion - Un champ TOC nouvellement inséré est vide jusqu’à ce que doc.updateFields() s’exécute, donc appelez‑le après avoir ajouté tout le contenu des titres.
Valider après l’insertion - Ouvrez le DOCX généré et mettez à jour les champs (Ctrl +A, F9) pour confirmer que les numéros de page sont corrects, surtout après d’autres modifications.
Réutiliser la chaîne de commutateur - Si vous générez plusieurs documents en lot, construisez la chaîne de commutateur une fois et réutilisez‑la dans les appels pour garder une mise en forme cohérente.

Conclusion

Ajouter une table des matières à un document Word en Java devient simple avec Conholdate.Total for Java. En créant un document, en insérant un champ TOC avec les commutateurs appropriés, en ajoutant du contenu formaté avec des titres, et en appelant updateFields, vous pouvez automatiser la création de rapports et de manuels professionnels. N’oubliez pas d’installer le SDK, de suivre les recommandations de bonnes pratiques et de tester la table des matières générée dans votre environnement cible. Pour les déploiements en production, vous aurez besoin d’une copie sous licence ; les détails des prix sont disponibles sur la page de tarification et une licence temporaire peut être obtenue sur la page de licence temporaire.

FAQs

Quelle est la façon la plus simple d’ajouter une table des matières à un document Word en Java ? Appelez builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u"), ajoutez des paragraphes au style titre, puis appelez doc.updateFields() avant d’enregistrer, comme le montre l’exemple de code.
Comment puis‑je contrôler quels niveaux de titres apparaissent dans la table des matières ? Modifiez la plage de niveaux à l’intérieur du commutateur \o de la chaîne passée à insertTableOfContents, par exemple \o "1-2" pour n’inclure que les niveaux 1 et 2.
Est-il possible de générer une table des matières (TOC) pour un modèle Word qui sera rempli plus tard ? Oui. Insérez le champ TOC dans le fichier modèle avant de remplir le contenu dynamique ; appeler updateFields() après l’ajout des titres remplira automatiquement la table des matières.
Ai-je besoin d’une connexion Internet pour utiliser ce SDK ? Non. Conholdate.Total for Java est une bibliothèque locale qui s’exécute sur votre serveur ou votre ordinateur de bureau sans aucun appel à un service externe.

Exemple complet fonctionnel d’ajout d’une table des matières à un document Word en Java#

Comprendre l’ajout de la table des matières à un document Word en code Java#

Installation et configuration de Conholdate.Total pour Java#

Meilleures pratiques pour générer une table des matières Word avec Java#

Conclusion#

FAQs#

En savoir plus#