Praca z listami
Przegląd
Ten przewodnik pokazuje, jak listy numerowane i punktowane są reprezentowane i kontrolowane w Aspose.Words FOSS dla .NET. List to wielokrotnego użytku definicja listy współdzielona przez każdy akapit, który ją używa, ListFormat to sposób, w jaki pojedynczy akapit odwołuje się do listy i jej bieżącego poziomu, a ListLevel przechowuje rzeczywiste formatowanie numeracji lub wypunktowania dla jednego poziomu listy.
Obiekt Listy i ListCollection
List reprezentuje jedną definicję listy — zasady numeracji, które dokument może zastosować do wielu akapitów. List.ListId identyfikuje ją, List.IsMultiLevel informuje, czy definiuje więcej niż jeden poziom, a List.ListLevels zwraca ListLevelCollection zawierający po jednym ListLevel na poziom, który lista definiuje. List.IsListStyleDefinition i IsListStyleReference rozróżniają listę, która definiuje własne formatowanie, od tej, która odwołuje się do formatowania poprzez powiązany Style (dostępny przez List.Style). Listy każdego dokumentu są dostępne przez Document.Lists, który zwraca ListCollection: ListCollection.Add(listTemplate) tworzy nową listę z jednego z predefiniowanych formatów ListTemplate programu Word, Add(listStyle) tworzy listę z Style, AddSingleLevelList(listTemplate) tworzy wariant jednopopoziomowy, a AddCopy(srcList) duplikuje istniejącą listę — przydatne, gdy chcesz, aby akapity miały niezależną numerację (świeży restart) zamiast współdzielić ten sam licznik. ListCollection.GetListByListId(listId) pobiera konkretną listę, a Count informuje, ile list ma dokument.
Zastosowanie list do akapitów przy użyciu ListFormat
ListFormat, dostępny z formatowania akapitu, kontroluje, do której listy należy akapit i na jakim poziomie. ListFormat.List to List używany przez akapit, a ListFormat.ListLevelNumber to poziom zerowy w tej liście; IsListItem informuje, czy akapit w ogóle jest częścią listy. ApplyBulletDefault() i ApplyNumberDefault() stosują domyślne formatowanie wypunktowane lub numerowane programu Word do akapitu w jednym wywołaniu, RemoveNumbers() usuwa formatowanie listy, a ListIndent()/ListOutdent() przenoszą akapit głębiej lub płytziej w poziomach listy — te same operacje, które Word wykonuje przy naciskaniu Tab lub Shift+Tab na początku akapitu listy.
Poziomy list i styl numeracji
ListLevel przechowuje formatowanie jednego poziomu listy: NumberStyle (wartość wyliczeniowa NumberStyle, np. cyfry arabskie lub cyfry rzymskie), NumberFormat (ciąg formatowania łączący liczbę z tekstem literalnym, takim jak kropka lub nawias), StartAt (liczba początkowa) oraz RestartAfterLevel (który wyższy poziom powoduje ponowne rozpoczęcie licznika tego poziomu). Alignment (wartość ListLevelAlignment: Left, Center, Right) oraz TrailingCharacter (wartość ListTrailingCharacter: Tab, Space, Nothing) kontrolują pozycję etykiety i jej oddzielenie od tekstu akapitu, wraz z TabPosition, NumberPosition i TextPosition dla precyzyjnego układu. IsLegal wymusza numerację w stylu prawnym (zawsze arabskie, niezależnie od NumberStyle), a LinkedStyle wiąże poziom z Style akapitu. Dla wypunktowań obrazkowych CreatePictureBullet() i DeletePictureBullet() zarządzają obrazkiem wypunktowania ImageData, a ListLevel.Font ustawia formatowanie samej liczby lub znaku wypunktowania. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) oblicza rzeczywistą wartość etykiety w danej pozycji w sekwencji numeracji.
Etykiety list i predefiniowane szablony
ListLabel opisuje renderowaną etykietę dla konkretnego wystąpienia elementu listy — LabelString to tekst literalny wyświetlany przez Word (np. „3.” lub „•”), LabelValue to podstawowa wartość numeryczna, a Font to formatowanie etykiety. ListTemplate jest wyliczeniem predefiniowanych formatów list w Word (style wypunktowań takie jak BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds oraz formaty numerowane), używany razem z ListCollection.Add(listTemplate) do rozpoczęcia od wbudowanego formatu zamiast budowania właściwości krok po kroku.
Wskazówki i najlepsze praktyki
- Użyj
ListCollection.AddCopy(srcList), gdy nowa grupa akapitów wymaga numeracji listy, która rozpoczyna się od nowa niezależnie, zamiast ponownego użyciaList, który jest już przypisany do innych akapitów. - Preferuj
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()dla standardowych list zamiast ręcznego konfigurowania każdej właściwościListLevel. - Sprawdź
List.IsListStyleReferencew porównaniu doIsListStyleDefinitionprzed bezpośrednią modyfikacją formatowania listy — formatowanie listy odwołującej się do stylu może być kontrolowane przez jej powiązanyStyle. - Ustaw
RestartAfterLevelexplicite na listach zagnieżdżonych, zamiast polegać na domyślnym zachowaniu restartu, gdy numeracja musi zostać zresetowana na określonych poziomach konspektu. - Użyj
ListFormat.ListIndent()/ListOutdent(), aby przenieść akapit między poziomami listy zamiast ustawiaćListLevelNumberbezpośrednio, ponieważ te metody utrzymują formatowanie listy akapitu wewnętrznie spójne.
Typowe problemy
| Problem | Przyczyna | Naprawa |
|---|---|---|
| Dwa akapity, które powinny być numerowane niezależnie, kontynuują tę samą sekwencję | Oba akapity ListFormat.List odnoszą się do tego samego współdzielonego obiektu List | Nadaj drugiemu akapitowi własną listę za pomocą ListCollection.AddCopy(srcList) zamiast ponownego użycia tego samego List |
| Niestandardowy ciąg formatu numeracji nie renderuje się zgodnie z oczekiwaniami | ListLevel.NumberFormat nie pasuje do oczekiwanego wzorca dla NumberStyle poziomu | Sprawdź, czy NumberFormat i NumberStyle są ustawione konsekwentnie dla edytowanego poziomu |
| Wcięcie listy wygląda nieprawidłowo po programowej zmianie poziomów | ListLevelNumber został ustawiony bezpośrednio bez aktualizacji powiązanych właściwości pozycji | Użyj ListFormat.ListIndent()/ListOutdent() zamiast bezpośredniego ustawiania ListLevelNumber |
| Punkt graficzny nie pojawia się | Nie utworzono punktu graficznego dla poziomu, lub domyślne formatowanie punktu tekstowego jest nadal aktywne | Wywołaj ListLevel.CreatePictureBullet() i dostarcz dane obrazu przed usunięciem formatowania punktu tekstowego |
FAQ
Jaka jest różnica między List a ListFormat?
List jest wielokrotnie używaną definicją numeracji/punktowania współdzieloną między akapitami; ListFormat jest przypisywane do poszczególnych akapitów — wskazuje, które List konkretny akapit używa i na którym poziomie, za pośrednictwem ListFormat.List i ListLevelNumber.
Jak sprawdzić, czy akapit jest częścią listy?
Przeczytaj ListFormat.IsListItem dotyczące formatowania akapitu; jeśli true, ListFormat.List i ListLevelNumber opisują, do której listy i poziomu on należy.
Jak sprawić, by nowa lista zaczynała numerację od 1 niezależnie od istniejącej listy?
Użyj ListCollection.AddCopy(srcList), aby utworzyć niezależną kopię definicji listy, a następnie zastosować tę kopię do nowych akapitów — zamiast ponownego użycia oryginalnego List, co spowodowałoby kontynuację tego samego licznika.
Jak utworzyć listę wypunktowaną lub numerowaną od podstaw?
Użyj ListFormat.ApplyBulletDefault() lub ApplyNumberDefault() dla domyślnego formatowania w programie Word, albo ListCollection.Add(listTemplate) z wartością ListTemplate, aby rozpocząć od jednego z predefiniowanych formatów programu Word i dostosować powstały List.ListLevels.
Jak kontrolować format numeracji, na przykład „1)” zamiast „1.”?
Ustaw ListLevel.NumberFormat na odpowiednim poziomie na żądany ciąg formatowania, wraz z NumberStyle określającym sam styl cyfr.
API Reference Podsumowanie
| Klasa/Metoda | Opis |
|---|---|
List | Definicja wielokrotnego użytku listy (numerowanej/punktowanej) |
ListCollection | Zbiór wszystkich list w dokumencie |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Utwórz listę z predefiniowanego szablonu lub skopiuj istniejącą |
ListFormat | Odwołanie per-akapitu do List i bieżącego poziomu |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Zastosuj domyślne formatowanie wypunktowania lub numeracji do akapitu |
ListLevel | Formatowanie numeracji/wypunktowania dla jednego poziomu List |
ListLevel.NumberStyle / NumberFormat | Styl liczbowy i ciąg formatu dla poziomu |
ListLabel | Renderowana etykieta (tekst i wartość) dla określonego elementu listy |
ListTemplate | Enum predefiniowanych formatów list programu Word |