Generare un indice navigabile è fondamentale quando si creano grandi report Word o manuali che gli utenti devono consultare rapidamente. Conholdate.Total for Java fornisce un SDK robusto che semplifica il lavoro con i file DOCX direttamente dalle applicazioni Java. In questa guida passo‑passo imparerai come aggiungere un indice a un documento Word in Java, coprendo l’installazione, la spiegazione del codice e le migliori pratiche.

Esempio completo funzionante per aggiungere un indice al documento Word in Java

Il seguente esempio dimostra come inserire un indice in un file DOCX esistente utilizzando Conholdate.Total for Java.

import com.groupdocs.words.Document;
import com.groupdocs.words.DocumentBuilder;
import com.groupdocs.words.TableOfContentsOptions;
import com.groupdocs.words.SaveFormat;
import com.groupdocs.words.TabLeader;

public class AddTableOfContentsExample {
    public static void main(String[] args) throws Exception {
        // Paths to the source and destination Word documents
        String inputPath = "input.docx";
        String outputPath = "output.docx";

// Load the existing document, add a TOC, and save the result
        try (Document doc = new Document(inputPath)) {
            DocumentBuilder builder = new DocumentBuilder(doc);

// Move cursor to the beginning of the document where the TOC will be inserted
            builder.moveToDocumentStart();

// Configure TOC options
            TableOfContentsOptions tocOptions = new TableOfContentsOptions();
            tocOptions.setUpperHeadingLevel(1);          // Include headings from level 1
            tocOptions.setLowerHeadingLevel(3);          // up to level 3
            tocOptions.setRightAlignPageNumbers(true);  // Align page numbers to the right
            tocOptions.setUseHyperlinks(true);           // Make entries clickable
            tocOptions.setTabLeader(TabLeader.DOTS);     // Use dotted leader

// Insert the Table of Contents
            builder.insertTableOfContents(tocOptions);

// Save the modified document
            doc.save(outputPath, SaveFormat.DOCX);
        }
    }
}

Nota: Questo esempio di codice dimostra la funzionalità principale. Prima di usarlo nel tuo progetto, assicurati di aggiornare i percorsi dei file (input.docx, output.docx, ecc.) per corrispondere alle tue effettive posizioni, verifica che tutte le dipendenze richieste siano installate correttamente e testa accuratamente nel tuo ambiente di sviluppo. Se incontri problemi, consulta la documentazione ufficiale o contatta il team di supporto per assistenza.

Comprendere l’aggiunta del sommario al documento Word in codice Java

Di seguito è riportata una suddivisione dei passaggi principali eseguiti dal codice di esempio:

  1. Carica il documento di origine - La classe Document legge il file DOCX esistente.

    try (Document doc = new Document(inputPath)) {

  2. Crea un DocumentBuilder - DocumentBuilder fornisce metodi per modificare il contenuto del documento.

    DocumentBuilder builder = new DocumentBuilder(doc);

  3. Posizionare il cursore - moveToDocumentStart() sposta il punto di inserimento all’inizio del file, garantendo che il TOC appaia prima di qualsiasi contenuto.

    builder.moveToDocumentStart();

  4. Configura le opzioni TOC - TableOfContentsOptions ti consente di definire i livelli di intestazione, l’allineamento dei numeri di pagina, l’uso dei collegamenti ipertestuali e lo stile del separatore di tabulazione.

TableOfContentsOptions tocOptions = new TableOfContentsOptions();
tocOptions.setUpperHeadingLevel(1);
tocOptions.setLowerHeadingLevel(3);
tocOptions.setRightAlignPageNumbers(true);
tocOptions.setUseHyperlinks(true);
tocOptions.setTabLeader(TabLeader.DOTS);

Una dettagliata documentazione API è disponibile nella pagina Riferimento API .

  1. Inserisci il TOC e salva - insertTableOfContents aggiunge il campo e doc.save scrive il file aggiornato in formato DOCX.
builder.insertTableOfContents(tocOptions);
doc.save(outputPath, SaveFormat.DOCX);

Installazione e Configurazione Conholdate.Total for Java

Aggiungi il repository Maven di Conholdate e la dipendenza SDK al tuo 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>

Scarica l’ultimo pacchetto SDK dalla pagina di download. L’SDK richiede Java 8 o versioni successive e funziona su qualsiasi JVM standard. Non sono necessari componenti runtime aggiuntivi.

Best Practices per la generazione del sommario Word con Java

  • Usa stili di intestazione coerenti - Il TOC rileva i paragrafi formattati con i livelli di intestazione predefiniti (Intestazione 1, Intestazione 2, ecc.). Assicurati che il documento di origine utilizzi questi stili per una generazione affidabile delle voci.
  • Limita la profondità delle intestazioni - Includere troppi livelli può rendere il TOC ingombrante. I report tipici usano i livelli 1‑3, come mostrato nell’esempio.
  • Abilita i collegamenti ipertestuali - Impostare setUseHyperlinks(true) crea voci cliccabili, migliorando la navigazione nel documento finale.
  • Convalida dopo l’inserimento - Apri il DOCX generato e aggiorna i campi (Ctrl +A, F9) per confermare che i numeri di pagina siano corretti, soprattutto dopo ulteriori modifiche.
  • Riutilizza l’oggetto delle opzioni del TOC - Se generi più documenti in batch, configura le opzioni una volta e riutilizzale per ridurre l’overhead di creazione degli oggetti.

Conclusione

Aggiungere un indice a un documento Word in Java diventa semplice con Conholdate.Total for Java. Caricando un DOCX, configurando TableOfContentsOptions e inserendo il campo, è possibile automatizzare la creazione di report e manuali professionali. Ricorda di installare l’SDK, seguire le raccomandazioni delle best‑practice e testare l’indice generato nell’ambiente di destinazione. Per le distribuzioni in produzione è necessaria una copia con licenza; i dettagli dei prezzi sono disponibili sulla pagina dei prezzi e una licenza temporanea può essere ottenuta dalla pagina della licenza temporanea.

Domande frequenti

  • Qual è il modo più semplice per aggiungere un indice a un documento Word in Java?
    Usa DocumentBuilder.moveToDocumentStart() seguito da insertTableOfContents con un oggetto TableOfContentsOptions configurato, come mostrato nell’esempio di codice.

  • Come posso controllare quali livelli di intestazione appaiono nel TOC?
    Imposta setUpperHeadingLevel e setLowerHeadingLevel sull’istanza TableOfContentsOptions per includere solo i livelli desiderati.

  • È possibile generare un TOC per un modello Word che verrà compilato in seguito?
    Sì. Inserisci il TOC nel file modello prima di popolare il contenuto dinamico; il TOC farà automaticamente riferimento alle intestazioni aggiunte in seguito.

  • Ho bisogno di una connessione internet per utilizzare questo SDK?
    No. Conholdate.Total per Java è una libreria locale che viene eseguita sul tuo server o desktop senza chiamate a servizi esterni.

Read More