Работа с таблицей содержимого

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

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

Включить таблицу содержимого программно

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

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

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

Следующий пример кода показывает, как вставить поле “Таблица содержимого” в документ:

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

Обновить таблицу содержимого

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

  1. Document.update_fields
  2. Document.update_page_layout

Обратите внимание, что эти два метода обновления должны быть названы в этом порядке. В обратном направлении таблица содержимого будет заполнена, но номера страниц не будут отображаться. Любое количество TOC может быть обновлено. Эти методы автоматически обновят все ТОС, найденные в документе.

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

Первый призыв к Document.update_fields будет строить <p notrans="<p notrans=” TOC"="">

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

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

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

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

По умолчанию эти переключатели выше включены при вставке по умолчанию TOC в документе. А. TOC без переключателей будет включать контент из встроенных стилей заголовков (как если бы переключатель \O установлен). Доступный TOC Переключатели, которые поддерживаются Aspose.Words Они перечислены ниже, и их использование подробно описано. Их можно разделить на отдельные разделы в зависимости от их типа. Переключатели в первом разделе определяют, какой контент включать в TOC и переключатели во втором разделе контролируют внешний вид ТОС. Если выключатель не указан здесь, то он в настоящее время не поддерживается. Все переключатели будут поддерживаться в будущих версиях. Мы добавляем дополнительную поддержку с каждым выпуском.

Вступление Marking Switchs

переключатель Описание
Heading Styles
(\O Switch)

Этот переключатель определяет, что TOC Они должны быть построены на основе встроенных стилей заголовков. в Microsoft Word Они определяются заголовком 1 - заголовком 9 В. Aspose.Words Эти стили представлены соответствующим перечислением идентификаторов стиля. Это перечисление представляет собой локальный независимый идентификатор стиля, например. StyleIdentifier.Heading1 Представляет стиль заголовка 1. Используя это, форматирование и свойства стиля могут быть извлечены из коллекции стиля документа. Соответствующий класс стиля можно извлечь из Document.Styles сбор с использованием индексированного свойства типа StyleIdentifier.

![working-with-table-of-contents-styles](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-2.png)

Любой контент, отформатированный с помощью этих стилей, включен в таблицу контента. Уровень заголовка будет определять соответствующий иерархический уровень входа в ТОС. Например, абзац со стилем заголовка 1 будет рассматриваться как первый уровень. `TOC` В то время как параграф с заголовком 2 будет рассматриваться как следующий уровень в иерархии и так далее.

| | **Outline Levels**
*(\U switch)* |

Каждый пункт может определять общий уровень в соответствии с вариантами пункта.

![working-with-table-of-contents-paragraph](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-3.png)

Этот параметр определяет, на каком уровне этот пункт должен рассматриваться в иерархии документов. Это обычно используемая практика, используемая для легкой структуры макета документа. Эту иерархию можно увидеть, изменив ее на Outline View. Microsoft Word. Как и в стилях заголовков, в дополнение к уровню "Телотекст" может быть от 1 до 9 уровней контура. Контурные уровни 1 - 9 появятся в `TOC` на соответствующем уровне иерархии
Любое содержание с уровнем контура, либо установленным в стиле абзаца, либо непосредственно на самом абзаце, включено в ТОС. в Aspose.Words Очертания уровня представлены `ParagraphFormat.OutlineLevel` Собственность Параграфного узла. Схемный уровень стиля абзаца представлен таким же образом `Style.ParagraphFormat` собственность.

| | **Custom Styles**
*(\T switch)* |

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

![working-with-table-of-contents-paragraph-settings](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-4.png)

Эти поля могут быть вставлены в документ в любом положении, как и любое другое поле, и представлены в виде `FieldType.FieldTOCEntry` перечисление.
Переключатель F в a `TOC` используется для указания того, что поля TC должны использоваться в качестве записей. Включение самостоятельно без дополнительного идентификатора означает, что в документ будет включено любое поле TC. Любой дополнительный параметр, часто одна буква, будет обозначать, что только поля TC, которые имеют соответствующий переключатель \f, будут включены в TOC. Например, *
{ TOC \f t }

Включает в себя только такие поля, как

{   TC \f t }

The `TOC` поле также имеет соответствующий переключатель, переключатель "\L" указывает, что в него включено только поле TC с уровнями в заданном диапазоне.

![todo:image_alt_text](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-5.png)

The `TC` Сами поля также могут иметь несколько коммутаторов. Это:

*F - описано выше. *

L - определяет, на каком уровне `TOC` Появится это поле ТК. А. `TOC` который использует этот же переключатель, будет включать это поле TC только в том случае, если оно находится в указанном диапазоне. *

- _\N - Номер страницы для этого `TOC` Вход не отображается. Образцовый код того, как вставить поля TC, можно найти в следующем разделе.

|

Связанные с внешним видом коммутаторы

переключатель Описание
Omit Page Numbers
(\N Switch)

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

{TOC \o "1-4" \n "3-4" }

и номера страниц на входах уровней 3 и четыре будут скрыты вместе с точками лидера (если таковые имеются). Чтобы указать только один уровень, диапазон все равно должен использоваться, например, "1-1" будет исключать номера страниц только для первого уровня.
При отсутствии диапазона уровней будут опущены номера страниц для всех уровней в TOC. Это полезно установить при экспорте документа в HTML или аналогичный формат. Это связано с тем, что форматы на основе HTML не имеют концепции страницы и, следовательно, не нуждаются в нумерации страницы.

![todo:image_alt_text](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-6.png)

| | **Insert As Hyperlinks**
*(\H Switch)* |

Этот переключатель указывает, что `TOC` Записи вставляются в виде гиперссылок. При просмотре документа в Microsoft Word Эти записи будут выглядеть как обычный текст внутри. `TOC` но являются гиперссылками и, таким образом, могут быть использованы для перехода в положение исходной записи в документе с помощью *Ctrl + Left Click* в Microsoft Word. Когда этот переключатель включен, эти ссылки также сохраняются в других форматах. Например, в форматах на основе HTML, включая EPUB и визуализированные форматы, такие как PDF и XPS Они будут экспортироваться как рабочие звенья.
Без этого переключателя установить `TOC` во всех этих выпусках будет экспортироваться как простой текст и не будет демонстрировать такое поведение. Если документ открыт в MS Word, текст записей также не будет кликабельным, но номера страниц все еще могут быть использованы для перехода к исходной записи.

![working-with-table-of-contents-titles](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-7.png)

| | **Set Separator Character**
*(\P Switch)* |

Этот переключатель позволяет легко изменять в TOC контент, разделяющий заголовок записи и нумерацию страницы. Сепаратор для использования должен быть указан после этого переключателя и заключен в речевые знаки.
Вопреки тому, что задокументировано в документации Office, можно использовать только один символ вместо пяти. Это касается как MS Word, так и Aspose.Words.
Использование этого переключателя не рекомендуется, поскольку он не позволяет контролировать то, что он использовал для разделения записей и номеров страниц в TOC. Вместо этого рекомендуется редактировать соответствующие `TOC` Стиль, такой как `StyleIdentifier.TOC1` и оттуда редактировать стиль лидера с доступом к конкретным шрифтам и т.д. Более подробную информацию о том, как это сделать, можно найти позже в статье.

![working-with-table-of-contents-toc](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-8.png)

| | **Preserve Tab Entries**
*(\W Switch)* |

Использование этого переключателя будет указывать, что любые записи, которые имеют символ вкладки, например заголовок, который имеет вкладку в конце строки, будут сохранены в качестве надлежащего символа вкладки при заполнении TOC. Это означает, что функция символа вкладки будет присутствовать в `TOC` Можно использовать для форматирования входа. Например, некоторые записи могут использовать стопы вкладок и символы вкладок, чтобы равномерно распределить текст. Если соответствующая `TOC` Уровень определяет эквивалентную остановку вкладки, затем генерируемую `TOC` Записи будут появляться с аналогичным интервалом.

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

![working-with-table-of-contents-aspose](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-9.png)

| | **Preserve New Line Entries**
*(\X Switch)* |

Подобно переключателю выше, этот переключатель указывает, что заголовки, охватывающие несколько строк (с использованием новых символов строки, а не отдельных абзацев), будут сохранены, поскольку они находятся в генерируемом TOC. Например, заголовок, который должен распространяться по нескольким линиям, может использовать новый символ строки (Ctrl + Enter). `ControlChar.LineBreak`) разделять контент по разным линиям. При указанном переключателе запись в `TOC` Мы сохраним эти новые символы, как показано ниже.

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

![working-with-table-of-contents-aspose-words](/words/python-net/working-with-table-of-contents/working-with-table-of-contents-10.png)

|

Включить TC Fields

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

Изменить таблицу содержимого

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

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

Также полезно отметить, что любое прямое форматирование параграфа (определяемого на самом параграфе, а не в стиле), помеченного как TOC Они будут скопированы в записи в TOC. Например, если стиль заголовка 1 используется для обозначения содержимого TOC Этот стиль имеет смелое форматирование, в то время как абзац также имеет курсивное форматирование, непосредственно применяемое к нему. В результате TOC Запись не будет смелой, так как это часть форматирования стиля, но она будет курсивом, поскольку это непосредственно отформатировано в пункте.

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

Используя Style класс, полученный для конкретного TOC Уровень, который вы хотите изменить, вы также можете изменить, как они отображаются в документе. Чтобы изменить то, как это выглядит в первую очередь Style.paragraph_format должен быть вызван, чтобы получить форматирование абзаца для стиля. Из этого стопы вкладки можно извлечь, позвонив ParagraphFormat.tab_stops и соответствующие вкладки перестают изменяться. Используя эту же технику, саму вкладку можно перемещать или удалять вместе. Ниже пример показывает, как изменить положение правильной остановки вкладки в TOC соответствующих параграфов.

Удалить таблицу содержимого из документа

Таблица содержимого может быть удалена из документа путем удаления всех узлов, найденных между FieldStart и FieldEnd узел TOC поле. Приведенный ниже код демонстрирует это. Удаление этого TOC Поле проще, чем обычное поле, так как мы не отслеживаем вложенные поля. Вместо этого мы проверяем FieldEnd Узел имеет тип FieldType.FIELD_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))