Arbeta med listor
Översikt
Denna guide visar hur numrerade och punktlistor representeras och styrs i Aspose.Words FOSS för .NET. En List är en återanvändbar listdefinition som delas av varje stycke som använder den, ListFormat är hur ett enskilt stycke refererar till en lista och dess nuvarande nivå, och ListLevel innehåller den faktiska nummer- eller punktformateringen för en nivå i en lista.
Listobjektet och ListCollection
List representerar en listdefinition — nummereringsreglerna som ett dokument kan tillämpa på många stycken. List.ListId identifierar den, List.IsMultiLevel rapporterar om den definierar mer än en nivå, och List.ListLevels returnerar en ListLevelCollection som innehåller en ListLevel per nivå som listan definierar. List.IsListStyleDefinition och IsListStyleReference skiljer en lista som definierar sin egen formatering från en som refererar till formatering via en länkad Style (tillgänglig via List.Style). Alla dokumentlistor nås via Document.Lists, som returnerar en ListCollection: ListCollection.Add(listTemplate) skapar en ny lista från ett av Words fördefinierade ListTemplate format, Add(listStyle) skapar en från en Style, AddSingleLevelList(listTemplate) skapar en enstegsvariant, och AddCopy(srcList) duplicerar en befintlig lista — användbart när du vill att stycken ska ha oberoende numrering (en ny start) snarare än att dela samma räknare. ListCollection.GetListByListId(listId) hämtar en specifik lista, och Count rapporterar hur många listor dokumentet har.
Applicera listor på stycken med ListFormat
ListFormat, nått via ett styckes formatering, styr vilken lista ett stycke tillhör och på vilken nivå. ListFormat.List är den List som stycket använder, och ListFormat.ListLevelNumber är den nollbaserade nivån inom den listan; IsListItem rapporterar om stycket överhuvudtaget är en del av en lista. ApplyBulletDefault() och ApplyNumberDefault() applicerar Words standardpunkt- eller nummerlistformat på ett stycke i ett anrop, RemoveNumbers() tar bort listformat, och ListIndent()/ListOutdent() flyttar ett stycke djupare in i eller grunda ut ur listans nivåer — samma operationer som Word utför när man trycker Tab eller Shift+Tab i början av ett liststycke.
Listnivåer och nummereringsstil
ListLevel innehåller formateringen för en nivå i en lista: NumberStyle (ett NumberStyle enum-värde såsom arabiska siffror eller romerska siffror), NumberFormat (formatsträngen som kombinerar siffran med bokstavlig text, t.ex. en punkt eller parentes), StartAt (startnumret) och RestartAfterLevel (vilken högre nivåens ökning återställer den här nivåns räknare). Alignment (ett ListLevelAlignment-värde: Left, Center, Right) och TrailingCharacter (ett ListTrailingCharacter-värde: Tab, Space, Nothing) styr hur etiketten placeras och separeras från stycketexten, tillsammans med TabPosition, NumberPosition och TextPosition för exakt layout. IsLegal tvingar juridisk stil-numrering (alltid arabiska, oavsett NumberStyle), och LinkedStyle kopplar nivån till ett stycke Style. För bildpunkter hanterar CreatePictureBullet() och DeletePictureBullet() en ImageData punktbild, och ListLevel.Font anger formateringen av siffran eller punkttecknet självt. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) beräknar det faktiska etikettvärdet på en given position i numreringssekvensen.
Listetiketter och fördefinierade mallar
ListLabel beskriver den renderade etiketten för en specifik listobjektinstans — LabelString är den bokstavliga texten som Word visar (t.ex. “3.” eller “•”), LabelValue är det underliggande numeriska värdet, och Font är etikettens formatering. ListTemplate är en enum av Words fördefinierade listformat (punktstilar såsom BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds och numrerade format), som används med ListCollection.Add(listTemplate) för att börja från ett inbyggt format snarare än att bygga en egenskap efter en annan.
Tips och bästa praxis
- Använd
ListCollection.AddCopy(srcList)när en ny grupp stycken behöver listnumrering som startar om oberoende, snarare än att återanvända enListsom redan är kopplad till andra stycken. - Föredra
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()för standardlistor istället för att manuellt konfigurera varjeListLevel-egenskap. - Kontrollera
List.IsListStyleReferencekontraIsListStyleDefinitioninnan du ändrar listformatering direkt — en stilrefererande listas formatering kan styras av dess länkadeStyleistället. - Ställ in
RestartAfterLevelexplicit på nästlade listor istället för att förlita dig på standardåterstarts-beteende när numreringen måste återställas på specifika dispositionsnivåer. - Använd
ListFormat.ListIndent()/ListOutdent()för att flytta ett stycke mellan listnivåer istället för att ställa inListLevelNumberdirekt, eftersom dessa metoder håller styckets listformatering internt konsekvent.
Vanliga problem
| Problem | Orsak | Lösning |
|---|---|---|
| Två stycken som bör numreras oberoende fortsätter samma sekvens | Båda styckenas ListFormat.List hänvisar till samma delade List objekt | Ge det andra stycket sin egen lista via ListCollection.AddCopy(srcList) istället för att återanvända samma List |
| En anpassad numreringsformatsträng renderas inte som förväntat | ListLevel.NumberFormat matchar inte det förväntade mönstret för nivåns NumberStyle | Verifiera att NumberFormat och NumberStyle är inställda konsekvent för den nivå som redigeras |
| Listindrag ser felaktigt ut efter att nivåerna ändrats programmässigt | ListLevelNumber sattes direkt utan att uppdatera relaterade positionsegenskaper | Använd ListFormat.ListIndent()/ListOutdent() istället för att sätta ListLevelNumber direkt |
| En bildpunkt visas inte | Ingen bildpunkt skapades för nivån, eller så är standardtextpunktformatering fortfarande aktiv | Anropa ListLevel.CreatePictureBullet() och ange bilddata innan du tar bort textpunktformatering |
FAQ
Vad är skillnaden mellan List och ListFormat?
List är den återanvändbara numrerings-/punktdefinitionen som delas mellan stycken; ListFormat är per stycke — den pekar på vilken List ett specifikt stycke använder och på vilken nivå, via ListFormat.List och ListLevelNumber.
Hur kontrollerar jag om ett stycke är en del av en lista?
Läs ListFormat.IsListItem om styckets formatering; om true, ListFormat.List och ListLevelNumber beskriver vilken lista och nivå det tillhör.
Hur får jag en ny lista att börja numrera från 1 oberoende av en befintlig lista?
Använd ListCollection.AddCopy(srcList) för att skapa en oberoende kopia av listdefinitionen, och sedan tillämpa kopian på de nya styckena — snarare än att återanvända den ursprungliga List, vilket skulle fortsätta samma räknare.
Hur skapar jag en punktlista eller en numrerad lista från grunden?
Använd ListFormat.ApplyBulletDefault() eller ApplyNumberDefault() för Word’s standardformatering, eller ListCollection.Add(listTemplate) med ett ListTemplate-värde för att börja från ett av Word’s fördefinierade format och anpassa det resulterande List.ListLevels därifrån.
Hur styr jag nummerformatet, till exempel “1)” istället för “1.”?
Ställ in ListLevel.NumberFormat på den relevanta nivån till önskad formatsträng, tillsammans med NumberStyle för själva siffrastilen.
API Reference Sammanfattning
| Klass/Metod | Beskrivning |
|---|---|
List | En återanvändbar listdefinition (numrering/punkt) |
ListCollection | Samlingen av alla listor i ett dokument |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Skapa en lista från en fördefinierad mall, eller kopiera en befintlig |
ListFormat | Referens per stycke till en List och den aktuella nivån |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Använd standardpunkt- eller numreringsformat för ett stycke |
ListLevel | Numrerings-/punktformatering för en nivå av en List |
ListLevel.NumberStyle / NumberFormat | Nummerstil och formatsträng för en nivå |
ListLabel | Den renderade etiketten (text och värde) för ett specifikt listobjekt |
ListTemplate | Enum av Words fördefinierade listformat |