Lavorare con le liste
Panoramica
Questa guida mostra come le liste numerate e puntate sono rappresentate e controllate in Aspose.Words FOSS per .NET. Un List è una definizione di lista riutilizzabile condivisa da ogni paragrafo che la utilizza, ListFormat è il modo in cui un singolo paragrafo fa riferimento a una lista e al suo livello corrente, e ListLevel contiene la formattazione effettiva di numerazione o puntatore per un livello di una lista.
L’oggetto Lista e ListCollection
List rappresenta una definizione di lista — le regole di numerazione che un documento può applicare a molti paragrafi. List.ListId la identifica, List.IsMultiLevel indica se definisce più di un livello, e List.ListLevels restituisce un ListLevelCollection contenente un ListLevel per ogni livello definito dalla lista. List.IsListStyleDefinition e IsListStyleReference distinguono una lista che definisce la propria formattazione da una che fa riferimento alla formattazione tramite un Style collegato (disponibile tramite List.Style). Le liste di ogni documento sono raggiungibili tramite Document.Lists, che restituisce un ListCollection: ListCollection.Add(listTemplate) crea una nuova lista da uno dei formati ListTemplate predefiniti di Word, Add(listStyle) ne crea una da un Style, AddSingleLevelList(listTemplate) crea una variante a livello singolo, e AddCopy(srcList) duplica una lista esistente — utile quando si desidera che i paragrafi abbiano una numerazione indipendente (un nuovo riavvio) anziché condividere lo stesso contatore. ListCollection.GetListByListId(listId) recupera una lista specifica, e Count segnala quante liste ha il documento.
Applicare le liste ai paragrafi con ListFormat
ListFormat, raggiunto dalla formattazione di un paragrafo, controlla a quale lista appartiene un paragrafo e a quale livello. ListFormat.List è il List che il paragrafo utilizza, e ListFormat.ListLevelNumber è il livello con indice zero all’interno di quella lista; IsListItem indica se il paragrafo fa parte di una lista. ApplyBulletDefault() e ApplyNumberDefault() applicano la formattazione di elenco puntato o numerato predefinita di Word a un paragrafo con una sola chiamata, RemoveNumbers() rimuove la formattazione dell’elenco, e ListIndent()/ListOutdent() spostano un paragrafo più in profondità o più superficialmente nei livelli della lista — le stesse operazioni che Word esegue premendo Tab o Shift+Tab all’inizio di un paragrafo di elenco.
Livelli della lista e stile di numerazione
ListLevel contiene la formattazione per un livello di un elenco: NumberStyle (un valore enum NumberStyle come numeri arabi o numeri romani), NumberFormat (la stringa di formato che combina il numero con testo letterale, ad esempio un punto o una parentesi), StartAt (il numero iniziale) e RestartAfterLevel (a quale livello superiore l’incremento ripristina il contatore di questo livello). Alignment (un valore ListLevelAlignment: Left, Center, Right) e TrailingCharacter (un valore ListTrailingCharacter: Tab, Space, Nothing) controllano come l’etichetta è posizionata e separata dal testo del paragrafo, insieme a TabPosition, NumberPosition e TextPosition per una disposizione precisa. IsLegal forza la numerazione in stile legale (sempre arabo, indipendentemente da NumberStyle), e LinkedStyle associa il livello a un Style del paragrafo. Per i punti elenco con immagine, CreatePictureBullet() e DeletePictureBullet() gestiscono un ImageData bullet image, e ListLevel.Font imposta la formattazione del numero o del carattere bullet stesso. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) calcola il valore effettivo dell’etichetta in una data posizione nella sequenza di numerazione.
Etichette di elenco e modelli predefiniti
ListLabel descrive l’etichetta renderizzata per una specifica istanza di elemento di elenco — LabelString è il testo letterale che Word visualizza (ad esempio “3.” o “•”), LabelValue è il valore numerico sottostante, e Font è la formattazione dell’etichetta. ListTemplate è un enum dei formati di elenco predefiniti di Word (stili puntati come BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds e formati numerati), usato con ListCollection.Add(listTemplate) per partire da un formato integrato anziché costruire una proprietà per volta.
Suggerimenti e migliori pratiche
- Usa
ListCollection.AddCopy(srcList)quando un nuovo gruppo di paragrafi necessita di una numerazione di elenco che ricomincia indipendentemente, invece di riutilizzare unListgià associato ad altri paragrafi. - Preferisci
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()per gli elenchi standard invece di configurare manualmente ogni proprietàListLevel. - Verifica
List.IsListStyleReferencerispetto aIsListStyleDefinitionprima di modificare direttamente la formattazione dell’elenco — la formattazione di un elenco che fa riferimento a uno stile potrebbe essere controllata dal suoStylecollegato. - Imposta
RestartAfterLevelesplicitamente sugli elenchi nidificati invece di fare affidamento sul comportamento predefinito di riavvio quando la numerazione deve ripristinarsi a livelli di struttura specifici. - Usa
ListFormat.ListIndent()/ListOutdent()per spostare un paragrafo tra i livelli di elenco invece di impostare direttamenteListLevelNumber, poiché questi metodi mantengono la formattazione dell’elenco del paragrafo coerente internamente.
Problemi comuni
| Problema | Causa | Correzione |
|---|---|---|
| Due paragrafi che dovrebbero essere numerati indipendentemente continuano la stessa sequenza | Il ListFormat.List di entrambi i paragrafi si riferisce allo stesso oggetto List condiviso | Assegna al secondo paragrafo la propria lista tramite ListCollection.AddCopy(srcList) invece di riutilizzare lo stesso List |
| Una stringa di formato di numerazione personalizzata non viene visualizzata come previsto | ListLevel.NumberFormat non corrisponde al modello previsto per il NumberStyle del livello | Verifica che NumberFormat e NumberStyle siano impostati in modo coerente per il livello in fase di modifica |
| L’indentazione dell’elenco sembra errata dopo aver modificato i livelli programmaticamente | ListLevelNumber è stato impostato direttamente senza aggiornare le proprietà di posizione correlate | Usa ListFormat.ListIndent()/ListOutdent() invece di impostare ListLevelNumber direttamente |
| Un punto elenco immagine non appare | Nessun punto elenco immagine è stato creato per il livello, oppure la formattazione predefinita del punto elenco di testo è ancora attiva | Chiama ListLevel.CreatePictureBullet() e fornisci i dati dell’immagine prima di rimuovere la formattazione del punto elenco di testo |
FAQ
Qual è la differenza tra List e ListFormat?
List è la definizione riutilizzabile di numerazione/punto condivisa tra i paragrafi; ListFormat è per paragrafo — indica quale List usa un paragrafo specifico e a quale livello, tramite ListFormat.List e ListLevelNumber.
Come verifico se un paragrafo fa parte di un elenco?
Leggi ListFormat.IsListItem sulla formattazione del paragrafo; se true, ListFormat.List e ListLevelNumber descrivono a quale elenco e livello appartiene.
Come faccio a far iniziare la numerazione di un nuovo elenco da 1 in modo indipendente da un elenco esistente?
Usa ListCollection.AddCopy(srcList) per creare una copia indipendente della definizione dell’elenco, quindi applica la copia ai nuovi paragrafi — anziché riutilizzare l’originale List, che continuerebbe lo stesso contatore.
Come creo un elenco puntato o numerato da zero?
Usa ListFormat.ApplyBulletDefault() o ApplyNumberDefault() per la formattazione predefinita di Word, oppure ListCollection.Add(listTemplate) con un valore ListTemplate per partire da uno dei formati predefiniti di Word e personalizzare il List.ListLevels risultante da lì.
Come posso controllare il formato del numero, ad esempio “1)” anziché “1.”?
Imposta ListLevel.NumberFormat al livello pertinente sul modello di formato desiderato, insieme a NumberStyle per lo stile del numero stesso.
API Reference Riepilogo
| Classe/Metodo | Descrizione |
|---|---|
List | Una definizione di elenco riutilizzabile (numerazione/punto) |
ListCollection | La raccolta di tutti gli elenchi in un documento |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Crea un elenco da un modello predefinito, o copia uno esistente |
ListFormat | Riferimento per paragrafo a un List e al livello corrente |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Applica la formattazione predefinita a punti o numerata a un paragrafo |
ListLevel | Formattazione di numerazione/punti per un livello di un List |
ListLevel.NumberStyle / NumberFormat | Lo stile numerico e la stringa di formato per un livello |
ListLabel | L’etichetta renderizzata (testo e valore) per un elemento di elenco specifico |
ListTemplate | Enum dei formati di elenco predefiniti di Word |