Gerar um índice navegável é essencial ao criar relatórios ou manuais extensos do Word que os usuários precisam percorrer 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 em funcionamento para adicionar Sumário a um documento Word em Java

O exemplo a seguir demonstra como inserir um índice em um arquivo DOCX usando 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");
    }
}

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar o diretório de saída (dataDir) para corresponder ao local real do seu arquivo, verifique se todas as dependências necessárias estão devidamente 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 como Adicionar Sumário a um Documento Word em Código Java

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

  1. Criar o documento e um construtor - Document representa o arquivo Word em memória, e DocumentBuilder fornece métodos para inserir conteúdo e campos nele.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

  1. Inserir o campo TOC - insertTableOfContents escreve um campo TOC na posição do cursor. A string de opções controla seu comportamento: \o "1-3" inclui os níveis de título de 1 a 3, \h torna as entradas hyperlinks clicáveis, \z oculta os líderes de tabulação e os números de página na visualização de layout da Web, e \u usa o nível de contorno aplicado aos parágrafos.

    builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

  2. Iniciar conteúdo em uma nova página - insertBreak(BreakType.PAGE_BREAK) move o corpo real do documento para a página após o sumário, de modo que o índice tenha sua própria página.

    builder.insertBreak(BreakType.PAGE_BREAK);

  3. Adicionar conteúdo com estilo de título - Definir setStyleIdentifier no formato de parágrafo do construtor para HEADING_1, HEADING_2 ou HEADING_3 antes de chamar writeln produz parágrafos estilizados com o estilo de título incorporado correspondente, que o campo TOC procura por entradas.

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

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

  1. Atualizar campos e salvar - doc.updateFields() preenche o sumário (TOC) com entradas e números de página agora que os cabeçalhos existem, e doc.save grava o documento no disco.
    doc.updateFields();
doc.save(dataDir + "TableOfContents.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 Sumário (TOC) do Word com Java

  • Use estilos de título consistentes - O sumário captura parágrafos formatados com os 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 confiáveis.
  • Limite a profundidade dos títulos - Incluir muitos níveis pode tornar o sumário difícil de manejar. Relatórios típicos usam níveis 1‑3, como mostrado na troca \o "1-3" do exemplo.
  • Habilite hyperlinks - Incluir a troca \h cria entradas clicáveis, melhorando a navegação no documento final.
  • Sempre chame updateFields após a inserção - Um campo de sumário recém‑inserido fica vazio até que doc.updateFields() seja executado, portanto chame‑o após todo o conteúdo de título ter sido adicionado.
  • Valide após a inserção - Abra o DOCX gerado e atualize os campos (Ctrl +A, F9) para confirmar que os números de página estão corretos, especialmente após novas edições.
  • Reutilize a string de troca - Se você gerar vários documentos em lote, construa a string de troca uma vez e reutilize‑a nas chamadas para manter a formatação consistente.

Conclusão

Adicionar um índice a um documento Word em Java torna‑se simples com Conholdate.Total for Java. Ao criar um documento, inserir um campo TOC com os switches apropriados, adicionar conteúdo com estilo de título e chamar updateFields, 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, será necessário 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? Chame builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u"), adicione parágrafos com estilo de título e, em seguida, chame doc.updateFields() antes de salvar, conforme demonstrado no exemplo de código.

  • Como posso controlar quais níveis de título aparecem no TOC? Altere o intervalo de níveis dentro da chave \o da string passada para insertTableOfContents, por exemplo \o "1-2" para incluir apenas os níveis 1 e 2.

  • É possível gerar um TOC para um modelo do Word que será preenchido posteriormente? Sim. Insira o campo TOC no arquivo de modelo antes de preencher o conteúdo dinâmico; chamar updateFields() depois que os títulos forem adicionados preencherá o TOC automaticamente.

  • 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