Работа со списками

Обзор

Это руководство показывает, как нумерованные и маркированные списки представлены и управляются в Aspose.Words FOSS для .NET. List — это переиспользуемое определение списка, которым делятся все абзацы, его использующие; ListFormat — это способ, которым отдельный абзац ссылается на список и его текущий уровень; а ListLevel содержит фактическое форматирование нумерации или маркера для одного уровня списка.


Объект списка и ListCollection

List представляет одно определение списка — правила нумерации, которые документ может применить к множеству абзацев. List.ListId идентифицирует его, List.IsMultiLevel сообщает, определяет ли он более одного уровня, а List.ListLevels возвращает ListLevelCollection, содержащий один ListLevel на каждый уровень, который определяет список. List.IsListStyleDefinition и IsListStyleReference различают список, который задаёт собственное форматирование, и список, который ссылается на форматирование через связанный Style (доступный через List.Style). Списки каждого документа доступны через Document.Lists, который возвращает ListCollection: ListCollection.Add(listTemplate) создаёт новый список из одного из предопределённых форматов ListTemplate Word, Add(listStyle) создаёт список из Style, AddSingleLevelList(listTemplate) создаёт одноуровневый вариант, а AddCopy(srcList) дублирует существующий список — полезно, когда вы хотите, чтобы абзацы имели независимую нумерацию (новый старт) вместо общего счётчика. ListCollection.GetListByListId(listId) извлекает конкретный список, а Count сообщает, сколько списков в документе.

Применение списков к абзацам с помощью ListFormat

ListFormat, получаемый из форматирования абзаца, управляет тем, к какому списку принадлежит абзац и на каком уровне. ListFormat.List — это List, используемый абзацем, а ListFormat.ListLevelNumber — это нулевой уровень внутри этого списка; IsListItem сообщает, является ли абзац частью списка вообще. ApplyBulletDefault() и ApplyNumberDefault() применяют к абзацу стандартное маркированное или нумерованное форматирование списка Word за один вызов, RemoveNumbers() удаляет форматирование списка, а ListIndent()/ListOutdent() перемещают абзац глубже в уровни списка или выше — те же операции, которые Word выполняет при нажатии Tab или Shift+Tab в начале абзаца списка.

Уровни списка и стиль нумерации

ListLevel хранит форматирование для одного уровня списка: NumberStyle (значение перечисления NumberStyle, например арабские цифры или римские цифры), NumberFormat (строка формата, объединяющая номер с буквальным текстом, например точка или скобка), StartAt (начальное число) и RestartAfterLevel (уровень выше, чей инкремент перезапускает счётчик этого уровня). Alignment (значение ListLevelAlignment: Left, Center, Right) и TrailingCharacter (значение ListTrailingCharacter: Tab, Space, Nothing) управляют расположением метки и её отделением от текста абзаца, вместе с TabPosition, NumberPosition и TextPosition для точного макета. IsLegal принуждает нумерацию в юридическом стиле (всегда арабские, независимо от NumberStyle), а LinkedStyle связывает уровень с абзацем Style. Для графических маркеров CreatePictureBullet() и DeletePictureBullet() управляют изображением маркера ImageData, а ListLevel.Font задаёт форматирование самого номера или символа маркера. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) вычисляет фактическое значение метки в заданной позиции последовательности нумерации.

Метки списков и предопределённые шаблоны

ListLabel описывает отрисованную метку для конкретного экземпляра пункта списка — LabelString является буквальным текстом, который отображает Word (например, “3.” или “•”), LabelValue — базовое числовое значение, а Font — форматирование метки. ListTemplate представляет перечисление предопределённых форматов списка Word (стили маркеров, такие как BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds, и нумерованные форматы), используемое с ListCollection.Add(listTemplate) для начала с встроенного формата вместо построения свойства за свойством.


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

  • Используйте ListCollection.AddCopy(srcList), когда новой группе абзацев требуется нумерация списка, начинающаяся заново независимо, вместо повторного использования List, уже прикреплённого к другим абзацам.
  • Отдавайте предпочтение ListFormat.ApplyNumberDefault() / ApplyBulletDefault() для стандартных списков вместо ручной настройки каждого свойства ListLevel.
  • Проверьте List.IsListStyleReference и IsListStyleDefinition перед прямым изменением форматирования списка — форматирование списка, ссылающегося на стиль, может управляться его связанным Style.
  • Установите RestartAfterLevel явно для вложенных списков, а не полагайтесь на поведение по умолчанию при перезапуске, когда нумерация должна сбрасываться на определённых уровнях структуры.
  • Используйте ListFormat.ListIndent()/ListOutdent() для перемещения абзаца между уровнями списков вместо прямой установки ListLevelNumber, поскольку эти методы сохраняют внутреннюю согласованность форматирования списка абзаца.

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

ПроблемаПричинаИсправление
Два абзаца, которые должны нумероваться независимо, продолжают одну и ту же последовательностьОба абзаца ListFormat.List ссылаются на один и тот же общий объект ListДайте второму абзацу собственный список через ListCollection.AddCopy(srcList), вместо повторного использования того же List
Пользовательская строка формата нумерации не отображается как ожидалосьListLevel.NumberFormat не соответствует ожидаемому шаблону для уровня NumberStyleУбедитесь, что NumberFormat и NumberStyle заданы последовательно для редактируемого уровня
Отступы списка выглядят неправильно после программного изменения уровнейListLevelNumber был установлен напрямую без обновления связанных свойств позицииИспользуйте ListFormat.ListIndent()/ListOutdent() вместо прямой установки ListLevelNumber
Изображение-маркер не отображаетсяДля уровня не был создан изображение-маркер, либо всё ещё активна форматировка маркера текста по умолчаниюВызовите ListLevel.CreatePictureBullet() и передайте данные изображения перед удалением форматирования текстового маркера

FAQ

В чём разница между List и ListFormat?

List — это многократно используемое определение нумерации/маркировки, общее для абзацев; ListFormat — это определение для отдельного абзаца — оно указывает, какой List использует конкретный абзац и на каком уровне, через ListFormat.List и ListLevelNumber.

Как проверить, является ли абзац частью списка?

Читайте ListFormat.IsListItem о форматировании абзаца; если true, ListFormat.List и ListLevelNumber описывают, к какому списку и уровню он относится.

Как заставить новый список начинать нумерацию с 1 независимо от существующего списка?

Используйте ListCollection.AddCopy(srcList), чтобы создать независимую копию определения списка, а затем примените копию к новым абзацам — вместо повторного использования оригинального List, который продолжал бы тот же счётчик.

Как создать маркированный или нумерованный список с нуля?

Используйте ListFormat.ApplyBulletDefault() или ApplyNumberDefault() для форматирования по умолчанию в Word, или ListCollection.Add(listTemplate) со значением ListTemplate, чтобы начать с одного из предустановленных форматов Word и настроить полученный List.ListLevels.

Как задать формат номера, например “1)” вместо “1.”?

Установите ListLevel.NumberFormat на соответствующем уровне в нужную строку формата, а также NumberStyle для самого стиля цифр.


API Reference Сводка

Класс/МетодОписание:
ListПовторно используемое определение списка (нумерация/маркировка)
ListCollectionКоллекция всех списков в документе
ListCollection.Add(listTemplate) / AddCopy(srcList)Создать список из предопределённого шаблона или скопировать существующий
ListFormatСсылка на List в каждом абзаце и текущий уровень
ListFormat.ApplyBulletDefault() / ApplyNumberDefault()Применить форматирование по умолчанию с маркерами или нумерацией к абзацу
ListLevelФорматирование нумерации/маркеров для одного уровня List
ListLevel.NumberStyle / NumberFormatСтиль нумерации и строка формата для уровня
ListLabelОтображаемая метка (текст и значение) для конкретного элемента списка
ListTemplateПеречисление предопределённых форматов списков Word

См. также:

 Русский