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