Como Trabalhar com Listas em .NET
Como trabalhar com listas em .NET
Listas numeradas e com marcadores em um documento do Word são construídas a partir de três objetos cooperantes: List, a definição reutilizável de numeração; ListFormat, que indica a um parágrafo específico a qual lista e nível ele pertence; e ListLevel, que contém a formatação real para um nível. Este guia mostra como aplicar uma lista a um parágrafo, impedir que listas separadas compartilhem um contador, mover parágrafos entre níveis e personalizar a formatação de numeração e marcadores com Aspose.Words FOSS para .NET.
Guia passo a passo
Etapa 1: Aplicar uma lista a um parágrafo
Use ListFormat.ApplyBulletDefault() ou ApplyNumberDefault() na formatação de um parágrafo para aplicar a lista de marcadores ou numerada padrão do Word em uma única chamada — esta é a maneira mais rápida de aplicar uma lista padrão. Para um formato predefinido específico em vez do padrão, chame Document.Lists (um ListCollection) .Add(listTemplate) com um valor ListTemplate como BulletDisk, BulletSquare, NumberArabicDot ou NumberUppercaseRomanDot para criar um List a partir de um dos formatos incorporados do Word, ou AddSingleLevelList(listTemplate) para uma variante de nível único. Uma vez que um parágrafo tem formatação de lista, ListFormat.IsListItem relata true, e ListFormat.List/ListLevelNumber identificam qual lista e nível ele usa.
Etapa 2: Dar a um novo grupo de parágrafos numeração independente
Parágrafos cujo ListFormat.List aponta para o mesmo objeto List compartilhado continuam o mesmo contador. Quando um novo grupo de parágrafos precisa de numeração que reinicie a partir de 1 independentemente, chame ListCollection.AddCopy(srcList) para duplicar uma definição de lista existente, então aplique a cópia aos novos parágrafos em vez de reutilizar a original. ListCollection.GetListByListId(listId) recupera uma lista específica pelo seu ListId quando você precisa localizar uma em vez de criar uma, e Count informa quantas listas o documento possui atualmente.
Etapa 3: Mover um parágrafo entre níveis de lista
Use ListFormat.ListIndent() para mover um parágrafo um nível mais profundo em sua lista, e ListOutdent() para movê-lo um nível menos profundo — as mesmas operações que o Word executa para Tab e Shift+Tab no início de um parágrafo de lista. Prefira esses métodos em vez de definir ListLevelNumber diretamente, pois eles mantêm a formatação de lista do parágrafo internamente consistente. Chame RemoveNumbers() para remover completamente a formatação de lista de um parágrafo.
Etapa 4: Personalizar o formato de numeração de um nível de lista
Alcance um nível específico através de List.ListLevels (um ListLevelCollection), então defina ListLevel.NumberStyle (um valor NumberStyle como Arabic, UppercaseRoman, LowercaseLetter ou Bullet) e NumberFormat — a string de formato que combina o número com texto literal, como um ponto ou parêntese — juntos, pois um par incompatível produz renderização inesperada. StartAt define o número inicial do nível, e RestartAfterLevel controla qual incremento de nível superior reinicia o contador deste nível — defina-o explicitamente em listas aninhadas em vez de depender do comportamento padrão de reinício. Alignment (Left, Center, Right) e TrailingCharacter (Tab, Space, Nothing) controlam a posição do rótulo e o separador entre o rótulo e o texto do parágrafo, juntamente com TabPosition, NumberPosition e TextPosition para layout preciso. IsLegal força a numeração no estilo jurídico (sempre arábica) independentemente de NumberStyle.
Etapa 5: Adicionar uma marca de imagem a um nível de lista
Chame ListLevel.CreatePictureBullet() no nível alvo para criar uma definição de marca de imagem, então forneça o ImageData da marca antes de remover qualquer formatação de marca de texto existente no mesmo nível. Chame DeletePictureBullet() para remover uma marca de imagem e reverter para a formatação de marca baseada em texto.
Etapa 6: Inspecionar o rótulo renderizado de um item de lista
ListLabel descreve o rótulo realmente renderizado para uma instância de item de lista, obtido a partir da formatação de parágrafo do item. LabelString é o texto literal que o Word exibe — como “3.” ou “•” — LabelValue é o valor numérico subjacente, e Font é a formatação própria do rótulo, independente da formatação do texto do parágrafo. Para calcular o valor de um rótulo em uma posição arbitrária na sequência sem renderizar toda a lista, chame ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat).
Problemas Comuns e Soluções
Dois parágrafos que devem ser numerados independentemente continuam a mesma sequência. Ambos os parágrafos’ ListFormat.List refere-se ao mesmo compartilhado List objeto. Dê ao segundo grupo sua própria lista via ListCollection.AddCopy(srcList) em vez de reutilizar o mesmo List.
Uma string de formato de numeração personalizada não é renderizada como esperado. ListLevel.NumberFormat não corresponde ao padrão esperado para o nível NumberStyle. Verificar NumberFormat and NumberStyle são definidas consistentemente para o nível que está sendo editado.
A indentação da lista parece errada após mudar os níveis programaticamente. ListLevelNumber foi definido diretamente sem atualizar as propriedades de posição relacionadas. Use ListFormat.ListIndent()/ListOutdent() em vez de definir ListLevelNumber diretamente.
Um marcador de imagem não aparece em um nível. Nenhum marcador de imagem foi criado para esse 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.
Uma lista vinculada a estilo não responde a alterações de formatação diretas. Check List.IsListStyleReference — a formatação de uma lista que referencia estilo é controlada por sua vinculada Style (via List.Style), não editando a lista diretamente. Compare com IsListStyleDefinition para distinguir uma lista que define sua própria formatação.
Perguntas Frequentes
Qual é a diferença entre List e ListFormat?
List é a definição reutilizável de numeração ou marcador compartilhada entre parágrafos. ListFormat é por parágrafo — aponta para qual List um parágrafo específico usa e em qual nível, via ListFormat.List e ListLevelNumber.
Como verifico se um parágrafo já faz parte de uma lista?
Leia ListFormat.IsListItem sobre a formatação do parágrafo. Se true, ListFormat.List e ListLevelNumber identificam a qual lista e nível ele pertence.
Como faço para que uma nova lista inicie a numeração a partir de 1 independentemente de uma lista existente?
Use ListCollection.AddCopy(srcList) para criar uma cópia independente da definição da lista, e então aplique a cópia aos novos parágrafos em vez de reutilizar o List original, que continuaria o mesmo contador.
Como crio 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 começar a partir de um formato predefinido e personalizar o List.ListLevels resultante a partir daí.
Como faço para obter um formato de número como “1)” em vez de “1.”?
Defina ListLevel.NumberFormat no nível relevante para a string de formato desejada, juntamente com NumberStyle para o estilo numeral em si.
