Работа с оглавлением

Часто вам приходится работать с документами, содержащими оглавление (TOC). Используя Aspose.Words, вы можете вставить свое собственное оглавление или полностью перестроить существующее оглавление в документе, используя всего несколько строк кода.

В этой статье описывается, как работать с полем оглавления, и демонстрируется:

• Как вставить совершенно новый TOC.
• Обновите новые или существующие TOCs в документе.
• Укажите параметры для управления форматированием и общей структурой TOC.
• Как изменить стили и внешний вид оглавления.
• Как удалить все поле TOC вместе со всеми записями из документа целиком.

Вставка оглавления программным способом

Вы можете вставить поле TOC (оглавление) в документ в текущей позиции, вызвав метод InsertTableOfContents.

Оглавление в документе Word может быть создано несколькими способами и отформатировано с использованием различных параметров. Переключатели полей, которые вы передаете методу, определяют способ создания и отображения таблицы в вашем документе.

Переключателями по умолчанию, которые используются в TOC, вставленном в Microsoft Word, являются "\o “1-3 \h \z \u”. Описания этих переключателей, а также список поддерживаемых переключателей можно найти далее в статье. Вы можете либо использовать это руководство для получения нужных переключателей, либо, если у вас уже есть документ, содержащий аналогичные TOC, которые вы хотите, вы можете показать коды полей (ALT+F9) и скопировать переключатели непосредственно из поля.

В следующем примере кода показано, как вставить поле оглавления в документ:

В следующем примере кода показано, как вставить оглавление (TOC) в документ, используя стили заголовков в качестве записей:

Код демонстрирует, что новое оглавление вставляется в пустой документ. Затем класс DocumentBuilder используется для вставки некоторого образца форматирования содержимого с соответствующими стилями заголовков, которые используются для обозначения содержимого, которое должно быть включено в TOC. Затем в следующих строках TOC заполняется путем обновления полей и макета страницы документа.

Без методов, использованных в примере, при открытии выходного документа вы бы обнаружили поле TOC, но без видимого содержимого. Это связано с тем, что поле TOC было вставлено, но еще не заполнено до тех пор, пока оно не будет обновлено в документе. Более подробная информация об этом приведена в следующем разделе.

Обновить оглавление

Aspose.Words позволяет полностью обновить TOC всего несколькими строками кода. Это можно сделать для заполнения только что вставленного TOC или для обновления существующего TOC после внесения изменений в документ.

Для обновления полей TOC в документе необходимо использовать следующие два метода:

1. Document.updateFields()
2. Document.updatePageLayout()

Пожалуйста, обратите внимание, что эти два метода обновления необходимо вызывать в указанном порядке. В обратном случае оглавление будет заполнено, но номера страниц отображаться не будут. Можно обновить любое количество различных TOCs. Эти методы автоматически обновят все TOCs, найденные в документе.

В следующем примере кода показано, как полностью перестроить поля TOC в документе, вызвав обновление полей:

Первый вызов Document.updateFields() приведет к созданию TOC, все текстовые записи будут заполнены, и TOC будет выглядеть почти завершенным. Единственное, чего не хватает, - это номеров страниц, которые на данный момент отображаются с помощью “?”.

При втором вызове функции Document.updatePageLayout() будет создан макет документа в памяти. Это необходимо сделать, чтобы получить номера страниц для записей. Правильные номера страниц, вычисленные в результате этого вызова, затем вставляются в TOC.

Используйте переключатели для управления поведением таблицы содержимого

Как и в случае с любым другим полем, поле TOC может принимать переключатели, определенные в коде поля, который управляет построением оглавления. Некоторые переключатели используются для управления тем, какие записи включаются и на каком уровне, в то время как другие используются для управления внешним видом TOC. Переключатели могут быть объединены вместе, что позволяет создать сложное оглавление.

По умолчанию эти параметры, указанные выше, включаются при вставке значения по умолчанию TOC в документ. Параметр TOC без каких-либо параметров будет включать содержимое из встроенных стилей заголовков (как если бы был установлен параметр \O).

Ниже перечислены доступные переключатели TOC, поддерживаемые Aspose.Words, и подробно описано их использование. Они могут быть разделены на отдельные разделы в зависимости от их типа. Переключатели в первом разделе определяют, какой контент следует включить в TOC, а переключатели во втором разделе управляют внешним видом TOC.

Если какого-либо переключателя здесь нет, значит, в данный момент он не поддерживается. Все переключатели будут поддерживаться в будущих версиях. Мы добавляем дополнительную поддержку в каждый выпуск.

Переключатели маркировки входа

Переключатель	Описание
Heading Styles * (Переключатель \O)*	Этот параметр определяет, что TOC должны быть созданы на основе встроенных стилей заголовков. В Microsoft Word они определены как Heading 1 – Heading 9. В Aspose.Words эти стили представлены соответствующим перечислением StyleIdentifier. Это перечисление представляет собой идентификатор стиля, не зависящий от языка, например, StyleIdentifier.Heading1 представляет стиль Heading 1. Используя это, форматирование и свойства стиля могут быть получены из коллекции стилей документа. Соответствующий класс стиля может быть извлечен из коллекции Document.Styles с помощью индексированного свойства типа StyleIdentifier. Любое содержимое, отформатированное с использованием этих стилей, включается в оглавление. Уровень заголовка будет определять соответствующий иерархический уровень записи в TOC. Например, абзац со стилем Heading 1 будет рассматриваться как первый уровень в TOC, тогда как абзац со стилем Heading 2 будет рассматриваться как следующий уровень в иерархии и так далее.
Outline Levels * (переключатель \U)*	Для каждого абзаца можно задать уровень структуры в разделе Параметры абзаца. Этот параметр определяет, на каком уровне иерархии документа следует рассматривать данный абзац. Это широко распространенная практика, используемая для упрощения структурирования макета документа. Эту иерархию можно просмотреть, переключившись в режим структуры в Microsoft Word. Как и в случае со стилями заголовков, в дополнение к уровню основного текста может быть от 1 до 9 уровней структуры. Уровни структуры с 1 по 9 будут отображаться в TOC на соответствующем уровне иерархии Любое содержимое с уровнем структуры, заданным либо в стиле абзаца, либо непосредственно в самом абзаце, включается в TOC. В Aspose.Words уровень структуры представлен свойством ParagraphFormat.OutlineLevel узла Абзаца. Уровень структуры стиля абзаца представлен таким же образом свойством Style.ParagraphFormat. Обратите внимание, что для встроенных стилей заголовков, таких как Heading 1, в настройках стиля обязательно устанавливается уровень контура.
Custom Styles * (переключатель \T)*	Этот параметр позволяет использовать пользовательские стили при сборе записей для использования в TOC. Этот параметр часто используется в сочетании с параметром \O для включения пользовательских стилей наряду со встроенными стилями заголовков в TOC. Параметры переключателя должны быть заключены в речевые знаки. Может быть включено множество пользовательских стилей, для каждого стиля следует указать название, за которым следует запятая, а затем уровень, на котором стиль должен отображаться в виде TOC. Другие стили также разделяются запятой. Например { TOC \o "1-3" \t "CustomHeading1, 1, CustomHeading2, 2"} будет использоваться контент, стилизованный под CustomHeading1, как контент уровня 1 в TOC и CustomHeading2 как контент уровня 2.
Используйте поля TC (переключатели\F и \L)	В старых версиях Microsoft Word единственным способом создания TOC было использование полей TC. Эти поля вставляются в документ скрытыми, даже если отображаются коды полей. Они содержат текст, который должен отображаться в записи, и на их основе создается TOC. Эта функциональность в настоящее время используется не очень часто, но все еще может быть полезна в некоторых случаях для включения записей в TOC, которые не имеют отступов, чтобы они были видны в документе. При вставке эти поля отображаются скрытыми, даже если отображаются коды полей. Их невозможно увидеть без отображения скрытого содержимого. Чтобы эти поля отображались, необходимо выбрать формат абзаца. Эти поля могут быть вставлены в документ в любом месте, как и любое другое поле, и представлены перечислением FieldType.FieldTOCEntry. Переключатель \F в TOC используется для указания того, что поля TC должны использоваться в качестве записей. Сам по себе переключатель без какого-либо дополнительного идентификатора означает, что будет включено любое поле TC в документе. Любой дополнительный параметр, часто состоящий из одной буквы, будет означать, что в список TOC будут включены только поля TC, которые имеют соответствующий переключатель \f. Например { TOC \f t } будет включать только TC полей, таких как { TC \f t } Поле TOC также имеет соответствующий переключатель, переключатель “\L” указывает, что включены только TC поля с уровнями в пределах указанного диапазона. Для самих полей TC также могут быть установлены переключатели {several, multiple, a few, many, numerous}. Это: - \F – Объяснено выше. - \L – Определяет, на каком уровне в TOC будет отображаться это поле TC. TOC, использующий этот же параметр, будет включать это поле TC только в том случае, если оно находится в пределах указанного диапазона. - _\N – Нумерация страниц для этой записи TOC не отображается.Пример кода того, как вставить TC полей, можно найти в следующем разделе.

Переключатели, связанные с внешним видом

Переключатель	Описание
Omit Page Numbers * (Переключатель \N)*	Этот параметр используется для скрытия номеров страниц для определенных уровней TOC. Например, вы можете задать {TOC \o "1-4" \n "3-4" } и номера страниц для записей уровней 3 и 4 будут скрыты вместе с точками выноски (если таковые имеются). Чтобы указать только один уровень, все равно следует использовать диапазон, например, “1-1” исключит номера страниц только для первого уровня. Указание диапазона уровней не приведет к пропуску номеров страниц для всех уровней в TOC. Это полезно установить при экспорте документа в HTML или аналогичный формат. Это связано с тем, что форматы, основанные на HTML, не имеют концепции страницы и, следовательно, не нуждаются в нумерации страниц.
Вставлять в виде гиперссылок (Переключатель \H)	Этот параметр указывает, что записи TOC вставляются в виде гиперссылок. При просмотре документа в Microsoft Word эти записи по-прежнему будут отображаться как обычный текст внутри TOC, но содержат гиперссылки и, таким образом, могут быть использованы для перехода к позиции исходной записи в документе с помощью Ctrl + Left Click в Microsoft Word. Когда этот параметр включен, эти ссылки также сохраняются в других форматах. Например, в форматах на основе HTML, включая EPUB, и в визуализированных форматах, таких как PDF и XPS, они будут экспортированы как рабочие ссылки. Без установки этого параметра TOC во всех этих выходных данных будет экспортироваться в виде обычного текста и не будет демонстрировать такое поведение. Если документ открыт в MS Word, текст записей также не будет доступен для просмотра таким образом, но номера страниц все равно можно использовать для перехода к исходной записи.
Set Separator Character * (Переключатель\P)*	Этот параметр позволяет легко изменять содержимое, разделяющее заголовок статьи и нумерацию страниц, в поле TOC. Разделитель, который следует использовать, должен быть указан после этого параметра и заключен в речевые знаки. Вопреки тому, что указано в документации Office, можно использовать только один символ вместо пяти. Это относится как к MS Word, так и к Aspose.Words. Использовать этот переключатель не рекомендуется, так как он не позволяет полностью контролировать то, что используется для разделения записей и номеров страниц в TOC. Вместо этого рекомендуется отредактировать соответствующий стиль TOC, например, StyleIdentifier.TOC1, а затем отредактировать стиль выноски с доступом к определенным элементам шрифта и т.д. Более подробную информацию о том, как это сделать, можно найти позже в статье.
Preserve Tab Entries * (Переключатель \W)*	Использование этого параметра приведет к тому, что любые записи, содержащие символ табуляции, например заголовок, в конце строки которого есть символ табуляции, будут сохранены как соответствующий символ табуляции при заполнении TOC. Это означает, что функция символа табуляции будет присутствовать в TOC и может быть использована для форматирования записи. Например, в некоторых записях могут использоваться точки и символы табуляции для равномерного выделения текста. До тех пор, пока соответствующий уровень TOC определяет эквивалентные интервалы табуляции, сгенерированные записи TOC будут отображаться с аналогичным интервалом. В аналогичной ситуации, если этот параметр не был задан, символы табуляции будут преобразованы в эквивалент пробелов как неработающие символы табуляции. В этом случае результат будет выглядеть не так, как ожидалось.
Preserve New Line Entries (Переключатель \X)	Аналогично описанному выше переключателю, этот параметр указывает, что заголовки, занимающие несколько строк (с использованием символов новой строки, а не отдельных абзацев), будут сохранены в том виде, в каком они есть в сгенерированном TOC. Например, в заголовке, который должен занимать несколько строк, можно использовать символ новой строки (Ctrl + Enter или ControlChar.LineBreak) для разделения содержимого в разных строках. При указании этого параметра запись в TOC сохранит эти новые символы строки, как показано ниже. В этой ситуации, если переключатель не определен, символы новой строки преобразуются в один пробел.

Вставить TC полей

Вы можете вставить новое поле TC в текущее положение DocumentBuilder, вызвав метод DocumentBuilder.InsertField и указав имя поля как “TC” вместе с любыми необходимыми параметрами.

В следующем примере кода показано, как вставить поле TC в документ с помощью DocumentBuilder.

Часто для TOC назначается определенная строка текста, которая помечается полем TC. Простой способ сделать это в MS Word - выделить текст и нажать ALT+SHIFT+O. При этом автоматически создается поле TC с использованием выделенного текста. Тот же метод может быть реализован с помощью кода. Приведенный ниже код найдет текст, соответствующий введенным данным, и вставит поле TC в том же месте, что и текст. Код основан на том же методе, который использовался в статье. В следующем примере кода показано, как найти и вставить поле TC в текст документа.

Изменить оглавление

Измените форматирование стилей

При форматировании записей в TOC не используются оригинальные стили отмеченных записей, вместо этого каждый уровень форматируется с использованием эквивалентного стиля TOC. Например, первый уровень в TOC отформатирован в стиле TOC1, второй уровень отформатирован в стиле TOC2 и так далее. Это означает, что для изменения внешнего вида TOC эти стили должны быть изменены. В Aspose.Words эти стили представлены не зависящими от языкового стандарта значениями от StyleIdentifier.TOC1 до StyleIdentifier.TOC9 и могут быть извлечены из коллекции Document.Styles с использованием этих идентификаторов.

Как только соответствующий стиль документа будет найден, форматирование для этого стиля может быть изменено. Любые изменения в этих стилях будут автоматически отражены в TOCs в документе.

В следующем примере кода изменяется свойство форматирования, используемое в стиле первого уровня TOC.

Также полезно отметить, что любое прямое форматирование абзаца (определенное в самом абзаце, а не в стиле), помеченное для включения в TOC, будет скопировано в запись в TOC. Например, если стиль Heading 1 используется для выделения содержимого для TOC, и этот стиль имеет полужирное оформление, в то время как к абзацу также непосредственно применяется курсивное форматирование. Результирующая запись TOC не будет выделена жирным шрифтом, поскольку это является частью форматирования стиля, однако она будет выделена курсивом, поскольку она отформатирована непосредственно в абзаце.

Вы также можете управлять форматированием разделителей, используемых между каждой записью и номером страницы. По умолчанию это пунктирная линия, которая пересекает нумерацию страниц с помощью символа табуляции и точки, расположенной рядом с правым полем.

Используя класс Style, полученный для конкретного уровня TOC, который вы хотите изменить, вы также можете изменить способ их отображения в документе.

Чтобы изменить внешний вид, сначала необходимо вызвать Style.ParagraphFormat, чтобы получить форматирование абзаца для стиля. После этого можно получить значения табуляции, вызвав ParagraphFormat.TabStops, и изменить соответствующее значение табуляции. Используя этот же метод, саму табуляцию можно переместить или вообще удалить.

В следующем примере кода показано, как изменить положение правой кнопки табуляции в связанных абзацах TOC.

Удаление оглавления из документа

Оглавление можно удалить из документа, удалив все узлы, находящиеся между узлами FieldStart и FieldEnd поля TOC.

Приведенный ниже код демонстрирует это. Удаление поля TOC проще, чем обычного поля, поскольку мы не отслеживаем вложенные поля. Вместо этого мы проверяем, что узел FieldEnd имеет тип FieldType.FieldTOC, что означает, что мы столкнулись с окончанием текущего TOC. Этот метод можно использовать в данном случае, не беспокоясь о каких-либо вложенных полях, поскольку мы можем предположить, что в любом правильно сформированном документе не будет полностью вложенного поля TOC внутри другого поля TOC.

Сначала собираются и сохраняются FieldStart узлы каждого TOC. Затем указанный TOC перечисляется, так что все узлы в поле просматриваются и сохраняются. Затем узлы удаляются из документа. В следующем примере кода показано, как удалить указанный TOC из документа.

Извлеките оглавление

Если вы хотите извлечь оглавление из любого документа Word, можно использовать следующий пример кода.