Работа с полями Index и Tables

Работа с полями индекса и таблиц

Это руководство показывает, как работать с семейством полей Word «Index and Tables» — полями, лежащими за таблицей содержимого, указателем, таблицей рисунков и таблицей источников. Каждый из них является подклассом Field в пространстве имён Aspose.Words.Fields: FieldToc (таблица содержимого или рисунков), FieldIndex (указатель), FieldXE (запись указателя), FieldToa (таблица источников), FieldTA (запись таблицы источников, или ссылка), FieldTC (запись таблицы содержимого) и FieldRD (ссылаемый документ, для построения объединённого указателя или таблицы содержимого в нескольких файлах).

Базовый класс поля

Каждый класс поля в этом семействе наследуется от Field, который предоставляет Start, Separator и End (узлы FieldStart, FieldSeparator и FieldEnd, ограничивающие поле в run stream), Type (значение FieldType — FieldTOC, FieldIndex, FieldTOA, FieldTOCEntry, FieldIndexEntry, FieldTOAEntry или FieldRefDoc для этого семейства), Result/DisplayResult (текущий вычисленный текст поля), IsLocked и IsDirty, а также методы GetFieldCode(), Update(), Unlink() и Remove(). Update() пересчитывает результат поля; для таблицы содержимого это означает перестроение списка записей из заголовков документа или маркеров FieldTC.

Вставка таблицы содержимого

DocumentBuilder.InsertTableOfContents(switches) вставляет FieldToc в текущую позицию построителя, используя строку переключателей поля Word (например "\o \"1-3\" \h \z \u") для управления тем, какие уровни заголовков включаются и как форматируется результат — те же переключатели, которые Word записывает при вставке Оглавления через пользовательский интерфейс. После вставки FieldToc.UpdatePageNumbers() пересчитывает часть с номерами страниц существующих записей. FieldToc также предоставляет свойства, напрямую управляющие структурой Оглавления: HeadingLevelRange и EntryLevelRange (какие уровни структуры включены), EntryIdentifier (идентификатор поля TC, который Оглавление должно собрать, для построения нескольких Оглавлений из разных маркеров FieldTC), InsertHyperlinks, PreserveTabs/PreserveLineBreaks, EntrySeparator/SequenceSeparator, BookmarkName, и — для таблицы рисунков, а не оглавления — TableOfFiguresLabel и CaptionlessTableOfFiguresLabel.

Маркировка пользовательских записей таблицы содержимого

Не каждый элемент оглавления (TOC) берётся из стиля заголовка. FieldTC помечает конкретное место как запись в оглавлении, независимую от стиля абзаца: FieldTC.Text — это текст записи, EntryLevel — уровень структуры, на котором она должна появиться, TypeIdentifier связывает её с FieldToc.EntryIdentifier при построении более чем одного оглавления, а OmitPageNumber подавляет номер страницы для этой записи.

Создание указателя

FieldIndex реализует поле INDEX, которое собирает метки FieldXE (запись указателя) документа в алфавитный указатель. FieldXE.Text — это текст записи, EntryType группирует записи в подуровни, используя синтаксис с двоеточиями, PageRangeBookmarkName помечает закладку, диапазон которой в указателе отображается как диапазон страниц, а не как один номер страницы, а IsBold/IsItalic форматируют полученную ссылку на страницу. С FieldIndex стороны, Heading вставляет разделители-буквы (A, B, C…), LetterRange ограничивает указатель подмножеством алфавита, RunSubentriesOnSameLine управляет расположением подзаписей, а PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator контролируют пунктуацию между записью и её ссылкой на страницу. FieldIndexFormat отдельно перечисляет встроенные визуальные стили указателя Word (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).

Таблица юридических источников

FieldToa и FieldTA являются эквивалентом FieldIndex/FieldXE для юридических источников: FieldTA помечает цитату в тексте (LongCitation и ShortCitation текст, EntryCategory для группировки под заголовком, например «Cases» или «Statutes», и IsBold/IsItalic для форматирования), а FieldToa собирает эти цитаты в таблицу, при этом EntryCategory выбирает, какую категорию собирать, UseHeading и UsePassim контролируют заголовки категорий и правило «passim» для часто цитируемых источников, а PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting управляют макетом.

Ссылка на содержимое из других документов

FieldRD реализует поле RD, которое указывает полю оглавления, указателя или таблицы юридических источников включать записи из другого файла при сборке — FieldRD.FileName это ссылка на документ, а IsPathRelative определяет, следует ли разрешать путь относительно текущего документа.

Советы и лучшие практики

• Создайте строку переключения оглавления так же, как делает Word (\o "1-3" \h \z \u), вместо того чтобы настраивать каждое свойство FieldToc по отдельности, а затем измените только те конкретные свойства, которые нужно изменить позже.
• Вызовите FieldToc.UpdatePageNumbers() (или Field.Update()) после изменения содержимого, чтобы оглавление, указатель или таблица авторитетов отражали текущий документ, а не устаревшие результаты с момента их вставки.
• Используйте FieldTC.TypeIdentifier совместно с FieldToc.EntryIdentifier, когда документ требует более одного оглавления (например, главное оглавление и отдельную таблицу рисунков), построенных из разных наборов записей.
• Установите FieldXE.PageRangeBookmarkName (или эквивалентную маркировку диапазона FieldTA), вместо того чтобы вручную форматировать диапазон страниц в тексте записи, чтобы указатель/оглавление оставались согласованными при перемещении содержимого.
• Помните, что номера страниц в результатах INDEX/TOC/TOA данного издания оцениваются как заполнительные значения, а не реальные номера страниц, поскольку макет страниц и нумерация не являются частью этого издания.

Распространённые проблемы

FAQ

Как программно вставить оглавление?

Вызовите DocumentBuilder.InsertTableOfContents(switches) со строкой переключателей в стиле Word, например "\o \"1-3\" \h \z \u", в позиции, где должен появиться оглавление.

Как пометить текст как запись индекса?

Вставьте поле FieldXE в этом месте (например через DocumentBuilder.InsertField) и установите его свойство Text равным тексту записи; FieldIndex собирает все маркеры FieldXE в документе в итоговый индекс.

В чём разница между FieldTC и записями оглавления, основанными на заголовках?

Стандартное поведение оглавления в Word собирает записи из абзацев, используя стили заголовков. FieldTC позволяет отметить произвольное место как запись оглавления независимо от стиля абзаца, которое FieldToc может включить, сопоставив значения EntryIdentifier/TypeIdentifier.

Как обновить оглавление или индекс после изменения документа?

Вызовите Update() для конкретного поля (например FieldToc.Update() или FieldToc.UpdatePageNumbers() только для номеров страниц), либо Document.UpdateFields(), чтобы обновить все поля в документе.

Можно ли собрать оглавление или индекс из нескольких документов?

Да — вставьте поле FieldRD, указывающее на каждый дополнительный документ через FileName; компилирующее поле (FieldToc, FieldIndex или FieldToa) включает записи из ссылочных документов при его обновлении.

API Reference Сводка

См. также:

• Aspose.Words for .NET — Enterprise Documentation