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

Огляд

У цьому посібнику показано, як нумеровані та марковані списки представляються та керуються у 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 — це перелік (enum) попередньо визначених форматів списків 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

Дивіться також

 Українська