Работа со списками
Обзор
Это руководство показывает, как нумерованные и маркированные списки представлены и управляются в 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 |