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 un List già associato ad altri paragrafi.
  • Preferisci ListFormat.ApplyNumberDefault() / ApplyBulletDefault() per gli elenchi standard invece di configurare manualmente ogni proprietà ListLevel.
  • Verifica List.IsListStyleReference rispetto a IsListStyleDefinition prima di modificare direttamente la formattazione dell’elenco — la formattazione di un elenco che fa riferimento a uno stile potrebbe essere controllata dal suo Style collegato.
  • Imposta RestartAfterLevel esplicitamente 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 direttamente ListLevelNumber, poiché questi metodi mantengono la formattazione dell’elenco del paragrafo coerente internamente.

Problemi comuni

ProblemaCausaCorrezione
Due paragrafi che dovrebbero essere numerati indipendentemente continuano la stessa sequenzaIl ListFormat.List di entrambi i paragrafi si riferisce allo stesso oggetto List condivisoAssegna 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 previstoListLevel.NumberFormat non corrisponde al modello previsto per il NumberStyle del livelloVerifica 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 programmaticamenteListLevelNumber è stato impostato direttamente senza aggiornare le proprietà di posizione correlateUsa ListFormat.ListIndent()/ListOutdent() invece di impostare ListLevelNumber direttamente
Un punto elenco immagine non appareNessun punto elenco immagine è stato creato per il livello, oppure la formattazione predefinita del punto elenco di testo è ancora attivaChiama 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/MetodoDescrizione
ListUna definizione di elenco riutilizzabile (numerazione/punto)
ListCollectionLa raccolta di tutti gli elenchi in un documento
ListCollection.Add(listTemplate) / AddCopy(srcList)Crea un elenco da un modello predefinito, o copia uno esistente
ListFormatRiferimento per paragrafo a un List e al livello corrente
ListFormat.ApplyBulletDefault() / ApplyNumberDefault()Applica la formattazione predefinita a punti o numerata a un paragrafo
ListLevelFormattazione di numerazione/punti per un livello di un List
ListLevel.NumberStyle / NumberFormatLo stile numerico e la stringa di formato per un livello
ListLabelL’etichetta renderizzata (testo e valore) per un elemento di elenco specifico
ListTemplateEnum dei formati di elenco predefiniti di Word

Vedi anche

 Italiano