Trabajando con Listas
Visión general
Esta guía muestra cómo se representan y controlan las listas numeradas y con viñetas en Aspose.Words FOSS para .NET. Un List es una definición de lista reutilizable compartida por cada párrafo que la usa, ListFormat es la forma en que un párrafo individual hace referencia a una lista y su nivel actual, y ListLevel contiene el formato real de numeración o viñeta para un nivel de una lista.
El objeto Lista y ListCollection
List representa una definición de lista — las reglas de numeración que un documento puede aplicar a muchos párrafos. List.ListId lo identifica, List.IsMultiLevel indica si define más de un nivel, y List.ListLevels devuelve un ListLevelCollection que contiene un ListLevel por nivel que la lista define. List.IsListStyleDefinition y IsListStyleReference distinguen una lista que define su propio formato de una que referencia el formato mediante un Style vinculado (disponible a través de List.Style). Las listas de cada documento se acceden mediante Document.Lists, que devuelve un ListCollection: ListCollection.Add(listTemplate) crea una nueva lista a partir de uno de los formatos ListTemplate predefinidos de Word, Add(listStyle) crea una a partir de un Style, AddSingleLevelList(listTemplate) crea una variante de un solo nivel, y AddCopy(srcList) duplica una lista existente — útil cuando se desea que los párrafos tengan numeración independiente (un reinicio nuevo) en lugar de compartir el mismo contador. ListCollection.GetListByListId(listId) recupera una lista específica, y Count indica cuántas listas tiene el documento.
Aplicando listas a párrafos con ListFormat
ListFormat, accesible desde el formato de un párrafo, controla a qué lista pertenece un párrafo y en qué nivel. ListFormat.List es el List que usa el párrafo, y ListFormat.ListLevelNumber es el nivel basado en cero dentro de esa lista; IsListItem indica si el párrafo forma parte de una lista o no. ApplyBulletDefault() y ApplyNumberDefault() aplican el formato de viñeta o lista numerada predeterminado de Word a un párrafo en una sola llamada, RemoveNumbers() elimina el formato de lista, y ListIndent()/ListOutdent() mueven un párrafo más profundo o más superficial en los niveles de la lista — las mismas operaciones que Word realiza al pulsar Tab o Shift+Tab al comienzo de un párrafo de lista.
Niveles de lista y estilo de numeración
ListLevel contiene el formato para un nivel de una lista: NumberStyle (un valor de enumeración NumberStyle como numerales arábigos o romanos), NumberFormat (la cadena de formato que combina el número con texto literal, como un punto o paréntesis), StartAt (el número inicial), y RestartAfterLevel (qué nivel superior reinicia el contador de este nivel). Alignment (un valor ListLevelAlignment: Left, Center, Right) y TrailingCharacter (un valor ListTrailingCharacter: Tab, Space, Nothing) controlan cómo se posiciona la etiqueta y se separa del texto del párrafo, junto con TabPosition, NumberPosition y TextPosition para un diseño preciso. IsLegal fuerza la numeración al estilo legal (siempre arábiga, sin importar NumberStyle), y LinkedStyle asocia el nivel con un Style de párrafo. Para viñetas de imagen, CreatePictureBullet() y DeletePictureBullet() gestionan una imagen de viñeta ImageData, y ListLevel.Font establece el formato del número o carácter de viñeta. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) calcula el valor real de la etiqueta en una posición dada de la secuencia de numeración.
Etiquetas de lista y plantillas predefinidas
ListLabel describe la etiqueta renderizada para una instancia específica de elemento de lista — LabelString es el texto literal que Word muestra (como “3.” o “•”), LabelValue es el valor numérico subyacente, y Font es el formato de la etiqueta. ListTemplate es una enumeración de los formatos de lista predefinidos de Word (estilos de viñeta como BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds, y formatos numerados), usado con ListCollection.Add(listTemplate) para iniciar a partir de un formato incorporado en lugar de construir una propiedad paso a paso.
Consejos y mejores prácticas
- Utilice
ListCollection.AddCopy(srcList)cuando un nuevo grupo de párrafos necesita una numeración de lista que comience de nuevo de forma independiente, en lugar de reutilizar unListque ya está adjunto a otros párrafos. - Prefiera
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()para listas estándar en lugar de configurar manualmente cada propiedadListLevel. - Verifique
List.IsListStyleReferencefrente aIsListStyleDefinitionantes de modificar el formato de la lista directamente — el formato de una lista que hace referencia a un estilo puede estar controlado por suStylevinculado. - Establezca
RestartAfterLevelde forma explícita en listas anidadas en lugar de confiar en el comportamiento de reinicio predeterminado cuando la numeración debe restablecerse en niveles de esquema específicos. - Utilice
ListFormat.ListIndent()/ListOutdent()para mover un párrafo entre niveles de lista en lugar de establecerListLevelNumberdirectamente, ya que estos métodos mantienen el formato de lista del párrafo internamente coherente.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
| Dos párrafos que deberían numerarse independientemente continúan la misma secuencia | El ListFormat.List de ambos párrafos se refiere al mismo objeto List compartido | Asigna al segundo párrafo su propia lista mediante ListCollection.AddCopy(srcList) en lugar de reutilizar el mismo List |
| Una cadena de formato de numeración personalizada no se muestra como se espera | ListLevel.NumberFormat no coincide con el patrón esperado para el NumberStyle del nivel | Verifique que NumberFormat y NumberStyle estén configurados de forma consistente para el nivel que se está editando |
| La sangría de la lista parece incorrecta después de cambiar los niveles programáticamente | ListLevelNumber se estableció directamente sin actualizar las propiedades de posición relacionadas | Utilice ListFormat.ListIndent()/ListOutdent() en lugar de establecer ListLevelNumber directamente |
| No aparece una viñeta de imagen | No se creó una viñeta de imagen para el nivel, o el formato de viñeta de texto predeterminado sigue activo | Llame a ListLevel.CreatePictureBullet() y proporcione los datos de la imagen antes de eliminar el formato de viñeta de texto |
FAQ
¿Cuál es la diferencia entre List y ListFormat?
List es la definición reutilizable de numeración/viñeta compartida entre párrafos; ListFormat es por párrafo — apunta a qué List utiliza un párrafo específico y a qué nivel, mediante ListFormat.List y ListLevelNumber.
¿Cómo puedo comprobar si un párrafo forma parte de una lista?
Lea ListFormat.IsListItem sobre el formato del párrafo; si true, ListFormat.List y ListLevelNumber describen a qué lista y nivel pertenece.
¿Cómo hago que una nueva lista comience la numeración desde 1 de forma independiente de una lista existente?
Use ListCollection.AddCopy(srcList) para crear una copia independiente de la definición de la lista, luego aplique la copia a los nuevos párrafos — en lugar de reutilizar el List original, lo que continuaría el mismo contador.
¿Cómo creo una lista con viñetas o numerada desde cero?
Use ListFormat.ApplyBulletDefault() o ApplyNumberDefault() para el formato predeterminado de Word, o ListCollection.Add(listTemplate) con un valor ListTemplate para comenzar desde uno de los formatos predefinidos de Word y personalizar el List.ListLevels resultante a partir de ahí.
¿Cómo controlo el formato del número, como “1)” en lugar de “1.”?
Establezca ListLevel.NumberFormat en el nivel correspondiente a la cadena de formato deseada, junto con NumberStyle para el estilo numeral en sí.
API Reference Resumen
| Clase/Método | Descripción |
|---|---|
List | Una definición de lista reutilizable (numeración/viñeta) |
ListCollection | La colección de todas las listas en un documento |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Crear una lista a partir de una plantilla predefinida, o copiar una existente |
ListFormat | Referencia por párrafo a un List y al nivel actual |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Aplicar formato de viñeta o numerado predeterminado a un párrafo |
ListLevel | Formato de numeración/viñeta para un nivel de un List |
ListLevel.NumberStyle / NumberFormat | El estilo numeral y la cadena de formato para un nivel |
ListLabel | La etiqueta renderizada (texto y valor) para un elemento de lista específico |
ListTemplate | Enumeración de los formatos de lista predefinidos de Word |