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 um List já associado a outros parágrafos.
  • Prefira ListFormat.ApplyNumberDefault() / ApplyBulletDefault() para listas padrão ao invés de configurar manualmente cada propriedade ListLevel.
  • Verifique List.IsListStyleReference vs IsListStyleDefinition antes de alterar a formatação da lista diretamente — a formatação de uma lista que referencia um estilo pode ser controlada pelo seu Style vinculado.
  • Defina RestartAfterLevel explicitamente 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 definir ListLevelNumber diretamente, pois esses métodos mantêm a formatação da lista do parágrafo internamente consistente.

Problemas comuns

ProblemaCausaCorreção
Dois parágrafos que deveriam ser numerados independentemente continuam na mesma sequênciaO ListFormat.List de ambos os parágrafos refere-se ao mesmo objeto List compartilhadoAtribua 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 esperadoListLevel.NumberFormat não corresponde ao padrão esperado para o NumberStyle do nívelVerifique 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 programaticamenteListLevelNumber foi definido diretamente sem atualizar as propriedades de posição relacionadasUse ListFormat.ListIndent()/ListOutdent() ao invés de definir ListLevelNumber diretamente
Um marcador de imagem não apareceNenhum marcador de imagem foi criado para o nível, ou a formatação padrão de marcador de texto ainda está ativaChame 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étodoDescrição
ListUma definição de lista reutilizável (numeração/marcação)
ListCollectionA 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
ListFormatReferê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
ListLevelFormatação de numeração/marcadores para um nível de um List
ListLevel.NumberStyle / NumberFormatO estilo numeral e a string de formato para um nível
ListLabelO rótulo renderizado (texto e valor) para um item de lista específico
ListTemplateEnum dos formatos de lista predefinidos do Word

Ver também

 Português