Trabalhando com Listas
Visão geral
Este guia mostra como listas numeradas e com marcadores são representadas e controladas no Aspose.Words FOSS para .NET. Um List é uma definição de lista reutilizável compartilhada por todos os parágrafos que a utilizam, ListFormat é a forma como um parágrafo individual referencia uma lista e seu nível atual, e ListLevel contém a numeração ou a formatação de marcadores real para um nível da lista.
O Objeto Lista e ListCollection
List representa uma definição de lista — as regras de numeração que um documento pode aplicar a vários parágrafos. List.ListId a identifica, List.IsMultiLevel informa se ela define mais de um nível, e List.ListLevels devolve um ListLevelCollection contendo um ListLevel por nível definido na lista. List.IsListStyleDefinition e IsListStyleReference distinguem uma lista que define sua própria formatação de uma que referencia formatação via um Style vinculado (disponível através de List.Style). As listas de cada documento são acessadas por Document.Lists, que devolve um ListCollection: ListCollection.Add(listTemplate) cria uma nova lista a partir de um dos formatos ListTemplate predefinidos do Word, Add(listStyle) cria uma a partir de um Style, AddSingleLevelList(listTemplate) cria uma variante de nível único, e AddCopy(srcList) duplica uma lista existente — útil quando você deseja que os parágrafos tenham numeração independente (uma reinicialização nova) em vez de compartilhar o mesmo contador. ListCollection.GetListByListId(listId) recupera uma lista específica, e Count indica quantas listas o documento possui.
Aplicando Listas a Parágrafos com ListFormat
ListFormat, acessado a partir da formatação de um parágrafo, controla a que lista o parágrafo pertence e em qual nível. ListFormat.List é o List que o parágrafo usa, e ListFormat.ListLevelNumber é o nível baseado em zero dentro dessa lista; IsListItem indica se o parágrafo faz parte de alguma lista. ApplyBulletDefault() e ApplyNumberDefault() aplicam a formatação padrão de marcadores ou de lista numerada do Word a um parágrafo em uma única chamada, RemoveNumbers() remove a formatação de lista, e ListIndent()/ListOutdent() movem o parágrafo para um nível mais profundo ou mais raso da lista — as mesmas operações que o Word executa ao pressionar Tab ou Shift+Tab no início de um parágrafo de lista.
Níveis da Lista e Estilo de Numeração
ListLevel contém a formatação para um nível de lista: NumberStyle (um valor enum NumberStyle como numerais arábicos ou romanos), NumberFormat (a string de formato que combina o número com texto literal, como ponto ou parêntese), StartAt (o número inicial), e RestartAfterLevel (qual nível superior reinicia o contador deste nível). Alignment (um valor ListLevelAlignment: Left, Center, Right) e TrailingCharacter (um valor ListTrailingCharacter: Tab, Space, Nothing) controlam a posição e o espaçamento do rótulo em relação ao texto do parágrafo, juntamente com TabPosition, NumberPosition e TextPosition para layout preciso. IsLegal impõe numeração no estilo jurídico (sempre arábico, independentemente de NumberStyle), e LinkedStyle associa o nível a um Style de parágrafo. Para marcadores de imagem, CreatePictureBullet() e DeletePictureBullet() gerenciam uma imagem de marcador ImageData, e ListLevel.Font define a formatação do número ou do caractere de marcador. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) calcula o valor real do rótulo em uma posição específica da sequência de numeração.
Rótulos de Lista e Modelos Predefinidos
ListLabel descreve o rótulo renderizado para uma instância específica de item de lista — LabelString é o texto literal que o Word exibe (como “3.” ou “•”), LabelValue é o valor numérico subjacente, e Font é a formatação do rótulo. ListTemplate é um enum dos formatos de lista predefinidos do Word (estilos de marcadores como BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds e formatos numerados), usado com ListCollection.Add(listTemplate) para iniciar a partir de um formato interno ao invés de construí-lo propriedade por propriedade.
Dicas e Melhores Práticas
- Use
ListCollection.AddCopy(srcList)quando um novo grupo de parágrafos requer numeração de lista que recomeça de forma independente, sem reutilizar umListjá associado a outros parágrafos. - Prefira
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()para listas padrão ao invés de configurar manualmente cada propriedadeListLevel. - Verifique
List.IsListStyleReferencevsIsListStyleDefinitionantes de alterar a formatação da lista diretamente — a formatação de uma lista que referencia um estilo pode ser controlada pelo seuStylevinculado. - Defina
RestartAfterLevelexplicitamente em listas aninhadas ao invés de depender do comportamento padrão de reinício quando a numeração precisa ser redefinida em níveis específicos de estrutura. - Use
ListFormat.ListIndent()/ListOutdent()para mover um parágrafo entre níveis de lista ao invés de definirListLevelNumberdiretamente, pois esses métodos mantêm a formatação da lista do parágrafo internamente consistente.
Problemas comuns
| Problema | Causa | Correção |
|---|---|---|
| Dois parágrafos que deveriam ser numerados independentemente continuam na mesma sequência | O ListFormat.List de ambos os parágrafos refere-se ao mesmo objeto List compartilhado | Atribua ao segundo parágrafo sua própria lista por meio de ListCollection.AddCopy(srcList), sem reutilizar o mesmo List |
| Uma string de formato de numeração personalizada não é exibida como esperado | ListLevel.NumberFormat não corresponde ao padrão esperado para o NumberStyle do nível | Verifique se NumberFormat e NumberStyle estão definidos de forma consistente para o nível que está sendo editado |
| A indentação da lista parece incorreta após alterar os níveis programaticamente | ListLevelNumber foi definido diretamente sem atualizar as propriedades de posição relacionadas | Use ListFormat.ListIndent()/ListOutdent() ao invés de definir ListLevelNumber diretamente |
| Um marcador de imagem não aparece | Nenhum marcador de imagem foi criado para o nível, ou a formatação padrão de marcador de texto ainda está ativa | Chame ListLevel.CreatePictureBullet() e forneça os dados da imagem antes de remover a formatação de marcador de texto |
FAQ
Qual é a diferença entre List e ListFormat?
List é a definição reutilizável de numeração/marcação compartilhada entre parágrafos; ListFormat é por parágrafo — indica qual List um parágrafo específico utiliza e em qual nível, por meio de ListFormat.List e ListLevelNumber.
Como verifico se um parágrafo faz parte de uma lista?
Consulte ListFormat.IsListItem na formatação do parágrafo; se true, ListFormat.List e ListLevelNumber descrevem a qual lista e nível ele pertence.
Como faço para que uma nova lista comece a numerar a partir de 1 independentemente de uma lista existente?
Use ListCollection.AddCopy(srcList) para criar uma cópia independente da definição da lista, então aplique a cópia aos novos parágrafos — em vez de reutilizar o List original, que continuaria o mesmo contador.
Como criar uma lista com marcadores ou numerada do zero?
Use ListFormat.ApplyBulletDefault() ou ApplyNumberDefault() para a formatação padrão do Word, ou ListCollection.Add(listTemplate) com um valor ListTemplate para iniciar a partir de um dos formatos predefinidos do Word e personalizar o List.ListLevels resultante.
Como controlo o formato do número, por exemplo “1)” ao invés de “1.”?
Defina ListLevel.NumberFormat no nível relevante com a cadeia de formato desejada, juntamente com NumberStyle para o estilo numérico em si.
API Reference Resumo
| Classe/Método | Descrição |
|---|---|
List | Uma definição de lista reutilizável (numeração/marcação) |
ListCollection | A coleção de todas as listas em um documento |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Crie uma lista a partir de um modelo predefinido ou copie uma existente |
ListFormat | Referência por parágrafo a um List e ao nível atual |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Aplicar formatação padrão de marcadores ou numeração a um parágrafo |
ListLevel | Formatação de numeração/marcadores para um nível de um List |
ListLevel.NumberStyle / NumberFormat | O estilo numeral e a string de formato para um nível |
ListLabel | O rótulo renderizado (texto e valor) para um item de lista específico |
ListTemplate | Enum dos formatos de lista predefinidos do Word |