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życia List, 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ści ListLevel.
  • Sprawdź List.IsListStyleReference w porównaniu do IsListStyleDefinition przed bezpośrednią modyfikacją formatowania listy — formatowanie listy odwołującej się do stylu może być kontrolowane przez jej powiązany Style.
  • Ustaw RestartAfterLevel explicite 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ć ListLevelNumber bezpośrednio, ponieważ te metody utrzymują formatowanie listy akapitu wewnętrznie spójne.

Typowe problemy

ProblemPrzyczynaNaprawa
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 ListNadaj 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 oczekiwaniamiListLevel.NumberFormat nie pasuje do oczekiwanego wzorca dla NumberStyle poziomuSprawdź, czy NumberFormat i NumberStyle są ustawione konsekwentnie dla edytowanego poziomu
Wcięcie listy wygląda nieprawidłowo po programowej zmianie poziomówListLevelNumber został ustawiony bezpośrednio bez aktualizacji powiązanych właściwości pozycjiUż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 aktywneWywoł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/MetodaOpis
ListDefinicja wielokrotnego użytku listy (numerowanej/punktowanej)
ListCollectionZbiór wszystkich list w dokumencie
ListCollection.Add(listTemplate) / AddCopy(srcList)Utwórz listę z predefiniowanego szablonu lub skopiuj istniejącą
ListFormatOdwołanie per-akapitu do List i bieżącego poziomu
ListFormat.ApplyBulletDefault() / ApplyNumberDefault()Zastosuj domyślne formatowanie wypunktowania lub numeracji do akapitu
ListLevelFormatowanie numeracji/wypunktowania dla jednego poziomu List
ListLevel.NumberStyle / NumberFormatStyl liczbowy i ciąg formatu dla poziomu
ListLabelRenderowana etykieta (tekst i wartość) dla określonego elementu listy
ListTemplateEnum predefiniowanych formatów list programu Word

Zobacz także

 Polski