Gerar um índice navegável é essencial ao criar relatórios Word extensos ou manuais que os usuários precisam folhear rapidamente. Conholdate.Total for Java fornece um SDK robusto que simplifica o trabalho com arquivos DOCX diretamente de aplicações Java. Neste guia passo a passo, você aprenderá como adicionar um índice a um documento Word em Java, cobrindo configuração, explicação do código e boas práticas.

Exemplo completo de funcionamento para adicionar Sumário a um documento Word em Java

O exemplo a seguir demonstra como inserir um índice em um arquivo DOCX existente usando 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: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar os caminhos dos arquivos (input.docx, output.docx, etc.) para corresponderem às suas localizações reais, verifique se todas as dependências necessárias estão corretamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter assistência.

Entendendo a Adição de Sumário a um Documento Word em Código Java

A seguir está uma divisão das principais etapas executadas pelo código de exemplo:

  1. Carregue o documento de origem - A classe Document lê o arquivo DOCX existente.
try (Document doc = new Document(inputPath)) {

  1. Criar um DocumentBuilder - DocumentBuilder fornece métodos para editar o conteúdo do documento.

    DocumentBuilder builder = new DocumentBuilder(doc);

  2. Posicionar o cursor - moveToDocumentStart() move o ponto de inserção para o início do arquivo, garantindo que o TOC apareça antes de qualquer conteúdo.

    builder.moveToDocumentStart();

  3. Configurar opções de TOC - TableOfContentsOptions permite definir níveis de cabeçalho, alinhamento de números de página, uso de hiperlinks e o estilo do líder de tabulação.

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

Referência detalhada da API está disponível na página Referência da API.

  1. Inserir o sumário e salvar - insertTableOfContents adiciona o campo, e doc.save grava o arquivo atualizado no formato DOCX.
builder.insertTableOfContents(tocOptions);
doc.save(outputPath, SaveFormat.DOCX);

Instalando e Configurando Conholdate.Total para Java

Adicione o repositório Maven da Conholdate e a dependência do SDK ao seu 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>

Baixe o pacote SDK mais recente na página de download. O SDK requer Java 8 ou superior e funciona em qualquer JVM padrão. Nenhum componente de tempo de execução adicional é necessário.

Melhores práticas para gerar o sumário do Word com Java

  • Use estilos de título consistentes - O sumário captura parágrafos formatados com níveis de título incorporados (Título 1, Título 2, etc.). Certifique‑se de que seu documento de origem use esses estilos para gerar entradas de forma confiável.
  • Limite a profundidade dos títulos - Incluir muitos níveis pode tornar o sumário difícil de manejar. Relatórios típicos utilizam níveis 1‑3, como mostrado no exemplo.
  • Habilite hyperlinks - Definir setUseHyperlinks(true) cria entradas clicáveis, melhorando a navegação no documento final.
  • Valide após a inserção - Abra o DOCX gerado e atualize os campos (Ctrl +A, F9) para confirmar que os números das páginas estão corretos, especialmente após novas edições.
  • Reutilize o objeto de opções do sumário - Se você gerar vários documentos em lote, configure as opções uma vez e reutilize‑as para reduzir a sobrecarga de criação de objetos.

Conclusão

Adicionar um índice a um documento Word em Java torna‑se simples com Conholdate.Total for Java. Carregando um DOCX, configurando TableOfContentsOptions e inserindo o campo, você pode automatizar a criação de relatórios e manuais profissionais. Lembre‑se de instalar o SDK, seguir as recomendações de boas práticas e testar o índice gerado no seu ambiente de destino. Para implantações em produção, você precisará de uma cópia licenciada; detalhes de preços estão disponíveis na página de preços e uma licença temporária pode ser obtida na página de licença temporária.

Perguntas Frequentes

  • Qual é a maneira mais simples de adicionar um índice a um documento Word em Java?
    Use DocumentBuilder.moveToDocumentStart() seguido de insertTableOfContents com um objeto TableOfContentsOptions configurado, conforme demonstrado no exemplo de código.

  • Como posso controlar quais níveis de cabeçalho aparecem no TOC?
    Defina setUpperHeadingLevel e setLowerHeadingLevel na instância TableOfContentsOptions para incluir apenas os níveis desejados.

  • É possível gerar um TOC para um modelo Word que será preenchido depois?
    Sim. Insira o TOC no arquivo de modelo antes de popular o conteúdo dinâmico; o TOC referenciará automaticamente os cabeçalhos adicionados posteriormente.

  • Preciso de uma conexão com a internet para usar este SDK?
    Não. Conholdate.Total for Java é uma biblioteca local que roda no seu servidor ou desktop sem chamadas a serviços externos.

Leia Mais