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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

working-with-table-of-contents-aspose-words-net

По умолчанию эти параметры, указанные выше, включаются при вставке параметра по умолчанию 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.
Use TC Fields * (Переключатели \F и \L)*	В старых версиях Microsoft Word единственным способом создания `TOC` было использование полей TC. Эти поля вставляются в документ скрытыми, даже если отображаются коды полей. Они содержат текст, который должен отображаться в записи, и на их основе создается `TOC`. Эта функциональность в настоящее время используется не очень часто, но все еще может быть полезна в некоторых случаях для включения записей в `TOC`, которые не имеют отступов, чтобы они были видны в документе. При вставке эти поля отображаются скрытыми, даже если отображаются коды полей. Их невозможно увидеть без отображения скрытого содержимого. Чтобы эти поля отображались, необходимо выбрать формат абзаца. Эти поля могут быть вставлены в документ в любом месте, как и любое другое поле, и представлены перечислением `FieldType.FieldTOCEntry`. Переключатель \F в `TOC` используется для указания того, что поля TC должны использоваться в качестве записей. Сам по себе переключатель без какого-либо дополнительного идентификатора означает, что будет включено любое поле TC в документе. Любой дополнительный параметр, часто состоящий из одной буквы, будет означать, что только TC полей, которые имеют соответствующий переключатель \f, будут включены в TOC. Например * `{ TOC \f t }` будет включать только TC полей, таких как `{ TC \f t }` Поле `TOC` также имеет соответствующий переключатель, переключатель “\L” указывает, что включены только TC поля с уровнями в пределах указанного диапазона. Для самих полей `TC` также может быть установлено несколько переключателей. Это: - \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, не имеют концепции страницы и, следовательно, не нуждаются в нумерации страниц.
Insert As Hyperlinks * (Переключатель \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.insert_field и указав имя поля как “TC” вместе с любыми необходимыми параметрами. В приведенном ниже примере показано, как вставить поле TC в документ с помощью DocumentBuilder.

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

При форматировании записей в 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.paragraph_format для получения форматирования абзаца для стиля. Из этого можно извлечь остановки табуляции, вызвав ParagraphFormat.tab_stops и изменив соответствующую остановку табуляции. Используя этот же метод, можно переместить или удалить саму табуляцию целиком. В приведенном ниже примере показано, как изменить положение правой остановки табуляции в TOC соответствующих абзацах.

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

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

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

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

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

doc = aw.Document(docs_base.my_dir + "Table of contents.docx")

for field in doc.range.fields :
            
    if (field.type == aw.fields.FieldType.FIELD_HYPERLINK) :
                
        hyperlink = field.as_field_hyperlink()
        if (hyperlink.sub_address != None and hyperlink.sub_address.find("_Toc") == 0) :
                    
            tocItem = field.start.get_ancestor(aw.NodeType.PARAGRAPH).as_paragraph()
                        
            print(tocItem.to_string(aw.SaveFormat.TEXT).strip())
            print("------------------")
    
            bm = doc.range.bookmarks.get_by_name(hyperlink.sub_address)
            pointer = bm.bookmark_start.get_ancestor(aw.NodeType.PARAGRAPH).as_paragraph()
                        
            print(pointer.to_string(aw.SaveFormat.TEXT))

Работа со сносками и заключением Работа с закладками в Python