Comment travailler avec les nœuds dans .NET
Ce guide montre comment parcourir, interroger et modifier l’arborescence des nœuds d’un document Word directement dans Aspose.Words FOSS pour .NET, en utilisant le Node and CompositeNode classes de base qui Document, Section, Paragraph, Table, et chaque autre élément de document sont construits sur. Il couvre la définition d’une portée de recherche par NodeType, ajouter et supprimer des nœuds programmatiquement, réagir aux changements structurels, et utiliser DocumentVisitor pour le parcours basé sur le type.
Guide étape par étape
Étape 1: installer le package
Aspose.Words FOSS pour .NET ne publie pas encore de package NuGet — compilez la bibliothèque à partir du code source à la place. Clonez https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, puis construisez Aspose.Words.sln en configuration Release avec le SDK .NET et référencez l’assembly Aspose.Words résultant depuis votre projet. La bibliothèque cible .NET Standard 2.0, elle s’exécute donc sur le Framework .NET 4.6.2+ et .NET 6/8/10.
Étape 2: importer les classes requises
Ajoutez une directive using Aspose.Words; — Node, CompositeNode, NodeType, NodeCollection, NodeList, INodeChangingCallback et DocumentVisitor se trouvent tous dans l’espace de noms Aspose.Words aux côtés de Document.
Étape 3: Comprendre le nœud et les classes de base CompositeNode
Chaque objet d’un arbre de document hérite de la classe abstraite Node, qui expose NodeType (identifiant le type de nœud), ParentNode (le CompositeNode englobant), Document (le document propriétaire), et PreviousSibling / NextSibling pour se déplacer parmi les nœuds au même niveau. Vérifiez Node.IsComposite pour savoir si un nœud donné peut contenir des enfants avant de le caster. CompositeNode étend Node pour les éléments conteneurs — FirstChild, LastChild et Count décrivent ses enfants immédiats, et HasChildNodes indique s’ils existent.
Étape 4: Interroger les enfants par type
Appelez CompositeNode.GetChildNodes(nodeType, isDeep) pour récupérer chaque enfant d’un NodeType donné, en passant isDeep: true pour rechercher dans tout le sous-arbre plutôt que seulement parmi les enfants directs, ou NodeType.Any pour faire correspondre chaque type de nœud quel qu’il soit. CompositeNode.GetChild(nodeType, index, isDeep) récupère un seul enfant correspondant par index. Pour les types de nœuds structurels (Document, Section, Body, Paragraph, Table, Row, Cell), les types de contenu en ligne (Run, Shape, Comment), et les types de mécanisme de champ (FieldStart, FieldSeparator, FieldEnd, qui marquent les limites d’un champ Word et le texte de commutation dans le flux d’exécution), passez la valeur NodeType spécifique qui identifie ce que vous recherchez.
Étape 5: Exécuter des requêtes XPath sur un sous-arbre
CompositeNode implémente également SelectNodes(xpath) et SelectSingleNode(xpath) pour des requêtes basées sur XPath à travers le sous-arbre, renvoyant les correspondances sous forme de NodeList (ou d’un seul Node). CompositeNode.GetEnumerator() prend en charge un simple foreach sur les enfants directs d’un nœud lorsque la requête XPath dépasse les besoins de la tâche.
Étape 6: Ajouter, déplacer et supprimer des nœuds
Pour modifier l’arbre, appelez AppendChild(newChild) ou PrependChild(newChild) pour ajouter un nœud au début ou à la fin des enfants d’un conteneur, et InsertBefore(newChild, refChild) ou InsertAfter(newChild, refChild) pour insérer relativement à un enfant existant. RemoveChild(oldChild) supprime un enfant, et RemoveAllChildren() efface tous les enfants d’un coup; CompositeNode.IndexOf(child) indique la position d’un enfant. Sur Node même, Clone(isCloneChildren) copie un nœud — éventuellement en incluant ses enfants — et Remove() détache le nœud de son parent.
Étape 7 : Matérialiser les nœuds avant de muter une collection en direct
Modifier une collection pendant qu’une boucle foreach l’itère — qu’il s’agisse d’un NodeCollection ou du résultat de GetChildNodes — génère une erreur. Appelez ToArray() sur la collection d’abord pour matérialiser les nœuds dans un tableau fixe, puis itérez sur ce tableau en appelant Remove() ou en apportant d’autres modifications à l’arbre.
Étape 8 : Parcourir un sous-arbre dans l’ordre du document
Node.NextPreOrder(rootNode) et PreviousPreOrder(rootNode) parcourent l’arbre dans l’ordre du document, limités par un nœud racine donné — une façon courante de scanner tout un sous-arbre nœud par nœud sans écrire de code de traversée récursive.
Étape 9 : Traiter chaque type de nœud avec DocumentVisitor
Pour traiter de nombreux types de nœuds différents de manière structurée, créez une sous-classe de la classe abstraite DocumentVisitor et surchargez les méthodes Visit*Start / Visit*End pour les types de nœuds qui importent — par exemple VisitParagraphStart / VisitParagraphEnd, VisitSectionStart / VisitSectionEnd, VisitBodyStart / VisitBodyEnd — puis appelez Node.Accept(visitor) sur la racine du sous-arbre pour l’exécuter. C’est le schéma standard pour exporter, transformer ou inspecter un document sans écrire de traversée récursive personnalisée pour chaque cas d’utilisation.
Étape 10 : Réagir aux changements structurels provenant d’un autre code
Mettez en œuvre INodeChangingCallback lorsque le code doit réagir aux insertions ou suppressions effectuées par d’autres code — y compris les opérations intégrées — et pas seulement aux changements réalisés directement. Ses méthodes NodeInserting(args), NodeInserted(args), NodeRemoving(args) et NodeRemoved(args) reçoivent chacune un NodeChangingArgs décrivant le Node affecté, son ancien et nouveau parent, ainsi que le NodeChangingAction (Insert ou Remove) qui s’est produit.
Problèmes courants et solutions
Le cast d’un nœud vers CompositeNode génère une erreur de conversion invalide Le nœud est de type feuille – par exemple Run or FieldStart – qui ne peut pas contenir d’enfants. Vérifiez Node.IsComposite d’abord, ou utilisez NodeType pour confirmer que le nœud est de type conteneur avant le transtypage.
GetChildNodes renvoie les enfants directs lorsque isDeep est false isDeep a été laissé false (ou omis lorsque la surcharge par défaut est superficielle). Passez isDeep: true to GetChildNodes() pour rechercher tout le sous-arbre au lieu des enfants immédiats.
Modifier une collection pendant son itération déclenche une erreur Des nœuds ont été ajoutés ou supprimés à l’intérieur d’un foreach sur un NodeCollection ou le résultat de GetChildNodes. Appeler ToArray() d’abord pour matérialiser les nœuds à modifier, puis itérer sur ce tableau tout en mutant l’arbre.
Une sous-classe DocumentVisitor n’est pas appelée pour certains contenus Le visiteur a été invoqué via Accept() sur un nœud qui ne contient pas réellement le contenu cible, ou le Visit* la méthode n’a pas été remplacée. Appelez Accept() sur un ancêtre qui contient le contenu, et remplacez chaque Visit*Start / Visit*End paire pertinente aux types de nœuds en cours de traitement.
INodeChangingCallback n’est pas notifié d’un changement Le rappel ne signale les changements que sur le Document à laquelle il a été enregistré. Vérifiez que le rappel est attaché au Document instance avant que le changement ne se produise, pas après.
Foire aux questions
Quelle est la différence entre Node et CompositeNode?
Node est la classe de base dont dérive chaque élément de document. CompositeNode étend Node pour les éléments qui peuvent contenir des enfants (comme Body, Paragraph et Table); les éléments feuilles tels que Run dérivent directement de Node et ne peuvent pas contenir d’enfants.
Comment trouver tous les nœuds d’un type spécifique dans un document?
Appelez CompositeNode.GetChildNodes(nodeType, isDeep) sur le nœud qui sert de racine à la recherche — souvent le Document lui-même — en passant le NodeType cible et isDeep: true pour chercher dans tout le sous-arbre, pas seulement parmi les enfants directs.
Comment supprimer des nœuds en toute sécurité pendant l’itération?
Collectez d’abord les nœuds à supprimer dans un tableau — par exemple avec NodeCollection.ToArray() — puis parcourez ce tableau et appelez Remove() sur chaque nœud, plutôt que de modifier la collection en direct pendant qu’un foreach l’itère.
Quels sont les nœuds FieldStart, FieldSeparator et FieldEnd?
Ce sont des valeurs NodeType marquant le mécanisme d’un champ Word intégré dans le flux d’exécution: FieldStart et FieldEnd délimitent le champ, et FieldSeparator sépare le code du champ de son résultat affiché actuellement.
Comment traiter chaque paragraphe, tableau et run dans un document?
Sous-classez DocumentVisitor, surchargez les méthodes Visit*Start / Visit*End pour les types de nœuds nécessaires, puis appelez Accept(visitor) sur le Document (ou toute racine de sous-arbre) pour l’exécuter.
