Travailler avec des listes
Travailler avec les listes
Ce guide montre comment les listes numérotées et à puces sont représentées et contrôlées dans Aspose.Words FOSS pour .NET. Un List est une définition de liste réutilisable partagée par chaque paragraphe qui l’utilise, ListFormat est la façon dont un paragraphe individuel fait référence à une liste et à son niveau actuel, et ListLevel contient le formatage réel de la numérotation ou de la puce pour un niveau de liste.
L’objet List et ListCollection
List représente une définition de liste — les règles de numérotation qu’un document peut appliquer à de nombreux paragraphes. List.ListId l’identifie, List.IsMultiLevel indique s’il définit plusieurs niveaux, et List.ListLevels renvoie un ListLevelCollection contenant un ListLevel par niveau défini par la liste. List.IsListStyleDefinition et IsListStyleReference distinguent une liste qui définit son propre formatage d’une liste qui référence le formatage via un Style lié (disponible via List.Style). Les listes de chaque document sont accessibles via Document.Lists, qui renvoie un ListCollection: ListCollection.Add(listTemplate) crée une nouvelle liste à partir de l’un des formats ListTemplate prédéfinis de Word, Add(listStyle) en crée une à partir d’un Style, AddSingleLevelList(listTemplate) crée une variante à niveau unique, et AddCopy(srcList) duplique une liste existante — utile lorsque vous voulez que les paragraphes aient une numérotation indépendante (un nouveau redémarrage) plutôt que de partager le même compteur. ListCollection.GetListByListId(listId) récupère une liste spécifique, et Count indique combien de listes le document possède.
Appliquer des listes aux paragraphes avec ListFormat
ListFormat, accessible depuis le formatage d’un paragraphe, contrôle à quelle liste un paragraphe appartient et à quel niveau. ListFormat.List est le List utilisé par le paragraphe, et ListFormat.ListLevelNumber est le niveau zero-based au sein de cette liste; IsListItem indique si le paragraphe fait partie d’une liste ou non. ApplyBulletDefault() et ApplyNumberDefault() appliquent le format de puce ou de liste numérotée par défaut de Word à un paragraphe en un seul appel, RemoveNumbers() supprime le format de liste, et ListIndent()/ListOutdent() déplacent un paragraphe plus profondément ou plus légèrement dans les niveaux de la liste — les mêmes opérations que Word effectue lorsqu’on appuie sur Tab ou Maj+Tab au début d’un paragraphe de liste.
Niveaux de liste et style de numérotation
ListLevel contient le formatage pour un niveau d’une liste: NumberStyle (une valeur d’énumération NumberStyle telle que des chiffres arabes ou des chiffres romains), NumberFormat (la chaîne de format combinant le numéro avec du texte littéral, comme un point ou une parenthèse), StartAt (le numéro de départ), et RestartAfterLevel (quel niveau supérieur déclenche le redémarrage du compteur de ce niveau). Alignment (une valeur ListLevelAlignment: Left, Center, Right) et TrailingCharacter (une valeur ListTrailingCharacter: Tab, Space, Nothing) contrôlent la position de l’étiquette et sa séparation du texte du paragraphe, ainsi que TabPosition, NumberPosition et TextPosition pour un agencement précis. IsLegal impose une numérotation de style juridique (toujours en arabe, quel que soit NumberStyle), et LinkedStyle associe le niveau à un Style de paragraphe. Pour les puces image, CreatePictureBullet() et DeletePictureBullet() gèrent une image de puce ImageData, et ListLevel.Font définit le format du numéro ou du caractère de puce lui-même. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) calcule la valeur réelle de l’étiquette à une position donnée dans la séquence de numérotation.
Étiquettes de listes et modèles prédéfinis
ListLabel décrit l’étiquette rendue pour une instance spécifique d’élément de liste — LabelString est le texte littéral affiché par Word (tel que «3.» ou «•»), LabelValue est la valeur numérique sous-jacent, et Font est le format de l’étiquette. ListTemplate est une énumération des formats de listes prédéfinis de Word (styles de puces tels que BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds, et formats numérotés), utilisé avec ListCollection.Add(listTemplate) pour partir d’un format intégré plutôt que de construire chaque propriété individuellement.
Conseils et meilleures pratiques
- Utilisez
ListCollection.AddCopy(srcList)lorsqu’un nouveau groupe de paragraphes nécessite une numérotation de liste qui repart à zéro de façon indépendante, plutôt que de réutiliser unListdéjà attaché à d’autres paragraphes. - Privilégiez
ListFormat.ApplyNumberDefault()/ApplyBulletDefault()pour les listes standard plutôt que de configurer manuellement chaque propriétéListLevel. - Vérifiez
List.IsListStyleReferencecontreIsListStyleDefinitionavant de modifier directement le format de la liste — le format d’une liste qui fait référence à un style peut être contrôlé par sonStyleassocié. - Définissez
RestartAfterLevelexplicitement sur les listes imbriquées plutôt que de compter sur le comportement de redémarrage par défaut lorsque la numérotation doit être réinitialisée à des niveaux de plan spécifiques. - Utilisez
ListFormat.ListIndent()/ListOutdent()pour déplacer un paragraphe entre les niveaux de liste au lieu de définirListLevelNumberdirectement, car ces méthodes maintiennent la mise en forme de la liste du paragraphe cohérente en interne.
Problèmes courants
| Problème | Cause | Correction |
|---|---|---|
| Deux paragraphes qui devraient être numérotés indépendamment continuent la même séquence | Le ListFormat.List des deux paragraphes fait référence au même objet List partagé | Donnez au deuxième paragraphe sa propre liste via ListCollection.AddCopy(srcList) au lieu de réutiliser le même List |
| Une chaîne de format de numérotation personnalisée ne s’affiche pas comme prévu | ListLevel.NumberFormat ne correspond pas au modèle attendu pour le NumberStyle du niveau | Vérifiez que NumberFormat et NumberStyle sont définis de manière cohérente pour le niveau en cours d’édition |
| L’indentation de la liste semble incorrecte après avoir changé les niveaux de façon programmatique | ListLevelNumber a été défini directement sans mettre à jour les propriétés de position associées | Utilisez ListFormat.ListIndent()/ListOutdent() au lieu de définir ListLevelNumber directement |
| Une puce image n’apparaît pas | Aucune puce image n’a été créée pour le niveau, ou le formatage de puce texte par défaut est toujours actif | Appelez ListLevel.CreatePictureBullet() et fournissez les données d’image avant de supprimer le formatage de puce texte |
FAQ
Quelle est la différence entre List et ListFormat?
List est la définition réutilisable de numérotation/puce partagée entre les paragraphes; ListFormat est propre à chaque paragraphe — il indique quel List un paragraphe spécifique utilise et à quel niveau, via ListFormat.List et ListLevelNumber.
Comment vérifier si un paragraphe fait partie d’une liste?
Lisez ListFormat.IsListItem sur le formatage du paragraphe; si true, ListFormat.List et ListLevelNumber décrivent à quelle liste et à quel niveau il appartient.
Comment faire en sorte qu’une nouvelle liste commence à numéroter à partir de 1 indépendamment d’une liste existante?
Utilisez ListCollection.AddCopy(srcList) pour créer une copie indépendante de la définition de la liste, puis appliquez la copie aux nouveaux paragraphes — plutôt que de réutiliser le List original, ce qui continuerait le même compteur.
Comment créer une liste à puces ou numérotée à partir de zéro?
Utilisez ListFormat.ApplyBulletDefault() ou ApplyNumberDefault() pour le formatage par défaut de Word, ou ListCollection.Add(listTemplate) avec une valeur ListTemplate pour partir de l’un des formats prédéfinis de Word et personnaliser le List.ListLevels résultant à partir de là.
Comment contrôler le format du numéro, par exemple «1)» au lieu de «1.»?
Définissez ListLevel.NumberFormat au niveau concerné sur la chaîne de format souhaitée, ainsi que NumberStyle pour le style de chiffre lui-même.
API Reference Résumé
| Classe/Méthode | Description |
|---|---|
List | Une définition de liste réutilisable (numérotation/puces) |
ListCollection | L’ensemble de toutes les listes d’un document |
ListCollection.Add(listTemplate) / AddCopy(srcList) | Créer une liste à partir d’un modèle prédéfini, ou copier une existante |
ListFormat | Référence par paragraphe à un List et au niveau actuel |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | Appliquer le format de puces ou de numérotation par défaut à un paragraphe |
ListLevel | Mise en forme de numérotation/puces pour un niveau d’un List |
ListLevel.NumberStyle / NumberFormat | Le style numérique et la chaîne de format pour un niveau |
ListLabel | L’étiquette rendue (texte et valeur) pour un élément de liste spécifique |
ListTemplate | Énumération des formats de liste prédéfinis de Word |