Comment travailler avec les listes dans .NET
Comment travailler avec les listes dans .NET
Les listes numérotées et à puces dans un document Word sont construites à partir de trois objets coopérants: List, la définition de numérotation réutilisable; ListFormat, qui indique à un paragraphe spécifique à quelle liste et à quel niveau il appartient; et ListLevel, qui contient le formatage réel pour un niveau. Ce guide montre comment appliquer une liste à un paragraphe, empêcher que des listes distinctes partagent un même compteur, déplacer des paragraphes entre les niveaux, et personnaliser le formatage des numéros et des puces avec Aspose.Words FOSS pour .NET.
Guide étape par étape
Étape 1: appliquer une liste à un paragraphe
Utilisez ListFormat.ApplyBulletDefault() ou ApplyNumberDefault() sur le formatage d’un paragraphe pour appliquer la puce ou la liste numérotée par défaut de Word en un seul appel — c’est la façon la plus rapide d’appliquer une liste standard. Pour un format prédéfini spécifique au lieu du défaut, appelez Document.Lists (un ListCollection) .Add(listTemplate) avec une valeur ListTemplate telle que BulletDisk, BulletSquare, NumberArabicDot ou NumberUppercaseRomanDot pour créer un List à partir d’un des formats intégrés de Word, ou AddSingleLevelList(listTemplate) pour une variante à niveau unique. Une fois qu’un paragraphe possède le formatage de liste, ListFormat.IsListItem signale true, et ListFormat.List/ListLevelNumber identifient la liste et le niveau utilisés.
Étape 2: attribuer à un nouveau groupe de paragraphes une numérotation indépendante
Les paragraphes dont le ListFormat.List pointe vers le même objet List partagé continuent le même compteur. Lorsqu’un nouveau groupe de paragraphes nécessite une numérotation qui redémarre à 1 de manière indépendante, appelez ListCollection.AddCopy(srcList) pour dupliquer une définition de liste existante, puis appliquez la copie aux nouveaux paragraphes au lieu de réutiliser l’original. ListCollection.GetListByListId(listId) récupère une liste spécifique par son ListId lorsque vous devez en rechercher une plutôt que d’en créer une, et Count indique combien de listes le document possède actuellement.
Étape 3 : Déplacer un paragraphe entre les niveaux de liste
Utilisez ListFormat.ListIndent() pour déplacer un paragraphe d’un niveau plus profond dans sa liste, et ListOutdent() pour le remonter d’un niveau — les mêmes opérations que Word effectue avec Tab et Maj+Tab au début d’un paragraphe de liste. Privilégiez ces méthodes plutôt que de définir ListLevelNumber directement, car elles maintiennent la mise en forme de liste du paragraphe cohérente en interne. Appelez RemoveNumbers() pour supprimer entièrement la mise en forme de liste d’un paragraphe.
Étape 4 : Personnaliser le format de numérotation d’un niveau de liste
Accédez à un niveau spécifique via List.ListLevels (un ListLevelCollection), puis définissez ListLevel.NumberStyle (une valeur NumberStyle telle que Arabic, UppercaseRoman, LowercaseLetter ou Bullet) et NumberFormat — la chaîne de format combinant le numéro avec du texte littéral tel qu’un point ou une parenthèse — ensemble, car une paire non concordante produit un rendu inattendu. StartAt définit le numéro de départ du niveau, et RestartAfterLevel contrôle quel incrément du niveau supérieur redémarre le compteur de ce niveau — définissez-le explicitement sur les listes imbriquées plutôt que de vous fier au comportement de redémarrage par défaut. Alignment (Left, Center, Right) et TrailingCharacter (Tab, Space, Nothing) contrôlent la position de l’étiquette et le séparateur entre l’étiquette et le texte du paragraphe, ainsi que TabPosition, NumberPosition et TextPosition pour une mise en page précise. IsLegal impose une numérotation de style juridique (toujours en chiffres arabes) quel que soit NumberStyle.
Étape 5 : Ajouter une puce image à un niveau de liste
Appelez ListLevel.CreatePictureBullet() sur le niveau cible pour créer une définition de puce image, puis fournissez le ImageData de la puce avant de supprimer toute mise en forme de puce texte existante sur le même niveau. Appelez DeletePictureBullet() pour supprimer une puce image et revenir à une mise en forme de puce basée sur du texte.
Étape 6 : Inspecter l’étiquette rendue d’un élément de liste
ListLabel décrit l’étiquette réellement rendue pour une instance d’élément de liste, obtenue à partir du formatage du paragraphe de l’élément. LabelString est le texte littéral affiché par Word — tel que «3.» ou «•» — LabelValue est la valeur numérique sous-jacente, et Font est le formatage propre de l’étiquette, indépendant du formatage du texte du paragraphe. Pour calculer la valeur d’une étiquette à une position arbitraire dans la séquence sans rendre toute la liste, appelez ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat).
Problèmes courants et solutions
Deux paragraphes qui doivent être numérotés indépendamment continuent la même séquence. Les deux paragraphes’ ListFormat.List se réfère au même partagé List objet. Donnez au deuxième groupe 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 niveau’s NumberStyle. Vérifier NumberFormat and 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 programmaticalement. ListLevelNumber a été défini directement sans mettre à jour les propriétés de position liées. Utilisez ListFormat.ListIndent()/ListOutdent() au lieu de définir ListLevelNumber directement.
Une puce image n’apparaît pas sur un niveau. Aucune puce image n’a été créée pour ce niveau, ou le formatage de puce texte par défaut est toujours actif. Appelez ListLevel.CreatePictureBullet() et fournissez les données de l’image avant de supprimer le formatage de puce texte.
Une liste liée à un style ne répond pas aux modifications de mise en forme directes. Check List.IsListStyleReference — la mise en forme d’une liste qui fait référence à un style est contrôlée par son lien Style (via List.Style), pas en modifiant la liste directement. Comparez avec IsListStyleDefinition pour distinguer une liste qui définit sa propre mise en forme.
Foire aux questions
Quelle est la différence entre List et ListFormat?
List est la définition réutilisable de numérotation ou de puce partagée entre les paragraphes. ListFormat est par paragraphe — elle indique quel List un paragraphe spécifique utilise et à quel niveau, via ListFormat.List et ListLevelNumber.
Comment vérifier si un paragraphe fait déjà partie d’une liste?
Lisez ListFormat.IsListItem sur le formatage du paragraphe. Si true, ListFormat.List et ListLevelNumber identifient la liste et le niveau auxquels il appartient.
Comment faire en sorte qu’une nouvelle liste commence la numérotation à 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 cette copie aux nouveaux paragraphes au lieu 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 d’un format prédéfini et personnaliser le List.ListLevels résultant à partir de là.
Comment obtenir un format de nombre comme “1)” au lieu de “1.”?
Définissez ListLevel.NumberFormat au niveau pertinent sur la chaîne de format souhaitée, ainsi que NumberStyle pour le style de chiffre lui-même.
