Добавить оглавление в документ Word на Java

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

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

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

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

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

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

Создайте документ и построитель - Document представляет собой в‑памяти файл Word, а DocumentBuilder предоставляет вам методы для вставки содержимого и полей в него.
```
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
```
Вставить поле оглавления - insertTableOfContents записывает поле оглавления в позиции курсора. Строка переключателей управляет его поведением: \o "1-3" включает уровни заголовков от 1 до 3, \h делает записи кликабельными гиперссылками, \z скрывает табуляцию и номера страниц в режиме веб‑разметки, а \u использует уровень структуры, применённый к абзацам.
```
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");
```
Начать содержимое на новой странице - insertBreak(BreakType.PAGE_BREAK) перемещает основное тело документа на страницу после оглавления, поэтому оглавление имеет свою собственную страницу.
```
builder.insertBreak(BreakType.PAGE_BREAK);
```
Добавить контент со стилем заголовка – Установка setStyleIdentifier в формате абзаца билдера на HEADING_1, HEADING_2 или HEADING_3 перед вызовом writeln создаёт абзацы, стилизованные соответствующим встроенным стилем заголовка, который поле TOC сканирует для создания записей.

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

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

Обновить поля и сохранить - doc.updateFields() заполняет оглавление (TOC) записями и номерами страниц, теперь когда заголовки существуют, и doc.save записывает документ на диск.
```
doc.updateFields();
doc.save(dataDir + "TableOfContents.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, как показано в переключателе \o "1-3" в примере.
Включите гиперссылки – Включение переключателя \h создаёт кликабельные записи, улучшая навигацию в итоговом документе.
Всегда вызывайте updateFields после вставки – Нововставленное поле оглавления пусто, пока не выполнится doc.updateFields(), поэтому вызывайте его после добавления всего содержимого заголовков.
Проверьте после вставки – Откройте сгенерированный DOCX и обновите поля (Ctrl +A, F9), чтобы убедиться, что номера страниц numbers правильные, особенно после дальнейших правок.
Повторно используйте строку переключателей – Если вы генерируете несколько документов в пакете, сформируйте строку переключателей один раз и повторно используйте её при вызовах, чтобы сохранить согласованность форматирования.

Заключение

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

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

Какой самый простой способ добавить оглавление в документ Word на Java? Вызовите builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u"), добавьте абзацы со стилем заголовка, затем вызовите doc.updateFields() перед сохранением, как показано в примере кода.
Как я могу контролировать, какие уровни заголовков отображаются в оглавлении? Измените диапазон уровней внутри переключателя \o в строке, передаваемой в insertTableOfContents, например \o "1-2" — чтобы включить только уровни 1 и 2.
Можно ли сгенерировать TOC (оглавление) для шаблона Word, который будет заполнен позже? Да. Вставьте поле TOC в файл шаблона до заполнения динамического контента; вызов updateFields() после добавления заголовков автоматически заполнит оглавление.
Нужен ли мне доступ к интернету для использования этого SDK? Нет. Conholdate.Total for Java — это локальная библиотека, которая работает на вашем сервере или настольном компьютере без каких-либо внешних вызовов сервисов.

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

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

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

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

Заключение#

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

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