Создание навигационного оглавления имеет решающее значение при создании крупных отчётов Word или руководств, которые пользователи должны быстро просмотреть. Conholdate.Total for Java предоставляет мощный SDK, упрощающий работу с файлами DOCX напрямую из Java‑приложений. В этом пошаговом руководстве вы узнаете, как добавить оглавление в документ Word на Java, охватывая настройку, объяснение кода и лучшие практики.

Полный рабочий пример добавления оглавления в документ Word на Java

В следующем примере демонстрируется, как вставить оглавление в существующий файл DOCX с использованием 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);
        }
    }
}

Примечание: Этот пример кода демонстрирует базовую функциональность. Прежде чем использовать его в вашем проекте, убедитесь, что обновили пути к файлам (input.docx, output.docx и т.д.) в соответствии с реальными расположениями, проверили, что все необходимые зависимости правильно установлены, и тщательно протестировали в вашей среде разработки. Если возникнут проблемы, обратитесь к официальной документации или свяжитесь с службой поддержки для получения помощи.

Понимание добавления оглавления в документ Word в Java‑коде

Ниже приведён разбор основных шагов, выполняемых образцом кода:

  1. Загрузить исходный документ - Класс Document читает существующий файл DOCX.
try (Document doc = new Document(inputPath)) {
  1. Создать DocumentBuilder - DocumentBuilder предоставляет методы для редактирования содержимого документа.
DocumentBuilder builder = new DocumentBuilder(doc);
  1. Позиционирование курсора - moveToDocumentStart() перемещает точку вставки в самое начало файла, гарантируя, что оглавление появится перед любым содержимым.
builder.moveToDocumentStart();
  1. Настройка параметров оглавления - TableOfContentsOptions позволяет задавать уровни заголовков, выравнивание номеров страниц, использование гиперссылок и стиль табуляции.
TableOfContentsOptions tocOptions = new TableOfContentsOptions();
tocOptions.setUpperHeadingLevel(1);
tocOptions.setLowerHeadingLevel(3);
tocOptions.setRightAlignPageNumbers(true);
tocOptions.setUseHyperlinks(true);
tocOptions.setTabLeader(TabLeader.DOTS);

Подробная справка по API доступна на странице API Reference.

  1. Вставьте оглавление и сохраните - insertTableOfContents добавляет поле, а doc.save записывает обновлённый файл в формате DOCX.
builder.insertTableOfContents(tocOptions);
doc.save(outputPath, SaveFormat.DOCX);

Установка и настройка Conholdate.Total для Java

Добавьте репозиторий Maven Conholdate и зависимость SDK в ваш 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>

Скачайте последнюю версию SDK с страницы загрузки. SDK требует Java 8 или выше и работает на любой стандартной JVM. Дополнительные компоненты среды выполнения не требуются.

Лучшие практики создания оглавления Word с помощью Java

  • Используйте согласованные стили заголовков – Оглавление (TOC) обнаруживает абзацы, оформленные встроенными уровнями заголовков (Heading 1, Heading 2 и т.д.). Убедитесь, что исходный документ использует эти стили для надёжного создания записей.
  • Ограничьте глубину заголовков – Слишком большое количество уровней может сделать оглавление громоздким. Обычно в отчётах используют уровни 1‑3, как показано в примере.
  • Включите гиперссылки – Установка setUseHyperlinks(true) создаёт кликабельные записи, улучшая навигацию в итоговом документе.
  • Проверьте после вставки – Откройте сгенерированный DOCX и обновите поля (Ctrl +A, F9), чтобы убедиться, что номера страниц numbers корректны, особенно после дальнейших правок.
  • Повторно используйте объект параметров TOC – Если вы генерируете несколько документов в пакете, настройте параметры один раз и повторно используйте их, чтобы снизить нагрузку на создание объектов.

Заключение

Добавление оглавления в документ Word на Java становится простым с помощью Conholdate.Total for Java. Загрузив DOCX, настроив TableOfContentsOptions и вставив поле, вы можете автоматизировать создание профессиональных отчетов и руководств. Не забудьте установить SDK, следовать рекомендациям по лучшим практикам и протестировать сгенерированное оглавление в целевой среде. Для производственных развертываний потребуется лицензированная копия; детали ценообразования доступны на странице с ценами и временную лицензию можно получить со страницы временной лицензии.

Часто задаваемые вопросы

  • Какой самый простой способ добавить оглавление в документ Word на Java?
    Используйте DocumentBuilder.moveToDocumentStart() и затем insertTableOfContents с настроенным объектом TableOfContentsOptions, как показано в примере кода.

  • Как я могу контролировать, какие уровни заголовков отображаются в оглавлении?
    Установите setUpperHeadingLevel и setLowerHeadingLevel в экземпляре TableOfContentsOptions, чтобы включить только нужные уровни.

  • Можно ли сгенерировать TOC для шаблона Word, который будет заполнен позже?
    Да. Вставьте TOC в файл шаблона до заполнения динамического контента; TOC автоматически будет ссылаться на заголовки, добавленные позже.

  • Нужен ли мне доступ к интернету для использования этого SDK?
    Нет. Conholdate.Total for Java — это локальная библиотека, которая работает на вашем сервере или настольном компьютере без внешних вызовов сервисов.

Читать дальше