Introduction
Ce guide examine comment Aspose.Words FOSS pour .NET représente un document Word en mémoire, et les API utilisées pour créer, parcourir et modifier cette représentation : DocumentBuilder pour la rédaction séquentielle, l’arborescence de nœuds (Node, CompositeNode, NodeCollection) pour un accès structurel direct, DocumentVisitor pour traiter chaque type de nœud en une seule passe, la recherche-remplacement via Range et FindReplaceOptions, ainsi que les méthodes de combinaison et de clonage de documents. Où l’article d’annonce présente la bibliothèque dans son ensemble, celui-ci reste concentré sur le modèle d’objet document (DOM) — la plus grande zone de la surface API — et sur la façon dont ses éléments s’assemblent.
Aspose.Words FOSS pour .NET est publié sous licence MIT sans dépendances natives ; il cible .NET Standard 2.0, de sorte que le DOM décrit ici est disponible sur .NET Framework 4.6.2+ et .NET 6, 8 et 10, sous Windows, Linux et macOS. Installez-le via NuGet, ou compilez-le à partir du code source — voir Quick Start ci-dessous.
Chaque tâche décrite ci-dessus — rédiger un rapport à partir de zéro, restructurer un fichier .docx existant, parcourir son contenu pour analyse, ou assembler plusieurs documents en un seul — part du même petit ensemble de types de base : Document, DocumentBuilder et la hiérarchie Node qui les sous-tend.
Le Document Object Model
Créer des documents avec DocumentBuilder
DocumentBuilder est un rédacteur basé sur un curseur qui repose sur un Document et insère le contenu séquentiellement. Write(text) et Writeln(text) ajoutent du texte à la position actuelle ; InsertParagraph() et InsertBreak(breakType) ajoutent des sauts de paragraphe et de page/colonne/section. Le formatage est état-dépendent : les propriétés Font, ParagraphFormat, ListFormat et PageSetup du builder s’appliquent à tout ce qui est écrit ensuite, et PushFont() / PopFont() sauvegardent et restaurent l’état de police actuel afin qu’un changement de style temporaire n’ait pas à être annulé manuellement. Les méthodes de navigation repositionnent le curseur n’importe où dans un document existant — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex), et la méthode polyvalente MoveTo(node) — et DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph et DocumentBuilder.CurrentSection indiquent où le builder se trouve actuellement. Pour l’extraction de texte en lecture seule où un DOM complet n’est pas nécessaire, PlainTextDocument offre une voie plus légère : new PlainTextDocument(fileName) expose uniquement la propriété PlainTextDocument.Text et les propriétés intégrées et personnalisées du document.
L’arbre de nœuds : Sections, Paragraphes, Runs et Tableaux
Un Document est un arbre d’objets Node dont la racine est le document lui-même : Section → Body → Paragraph → Run pour le texte du corps, avec Table → Row → Cell qui se ramifient chaque fois qu’une table apparaît. CompositeNode, la classe de base de chaque nœud conteneur, expose CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling et Node.PreviousSibling pour une traversée directe, GetChildNodes(nodeType, isDeep) pour collecter chaque nœud d’un NodeType donné (Paragraph, Run, Table, etc.) à n’importe quelle profondeur, et GetChild(nodeType, index, isDeep) pour des recherches indexées. AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) et RemoveChild(oldChild) modifient l’arbre directement. CompositeNode.SelectNodes(xpath) et SelectSingleNode(xpath) sélectionnent des nœuds avec une expression de type XPath au lieu de parcourir l’arbre manuellement, et pour les très gros documents, Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) parcourent chaque nœud un à un sans récursion.
DocumentVisitor : Traitement de chaque type de nœud en un seul passage
La sous-classe de DocumentVisitor est la manière de traiter un document sans coder en dur sa structure. Elle définit des méthodes appariées Visit-Start / Visit-End pour chaque type de nœud composite, y compris DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart et DocumentVisitor.VisitBookmarkStart — chacune avec un rappel End correspondant — ainsi que DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd et DocumentVisitor.VisitRun pour les unités de texte individuelles. Appelez Accept(visitor) sur un Document, Section ou tout autre nœud pour exécuter le visiteur sur ce nœud et tout ce qui se trouve en dessous ; AcceptStart(visitor) et AcceptEnd(visitor) invoquent uniquement les rappels d’entrée et de sortie pour un seul nœud composite. Chaque méthode Visit renvoie une valeur VisitorAction qui contrôle la façon dont la traversée se poursuit — Continue dans le sous-arbre, SkipThisNode pour l’ignorer, ou Stop pour arrêter complètement.
Recherche et remplacement de texte
Range.Replace(pattern, replacement) effectue une recherche-remplacement sur le Range qui le possède — un Document complet, une Section ou la propriété Range propre à n’importe quel nœud — avec le motif de recherche accepté soit comme chaîne littérale, soit comme expression régulière. La surcharge Range.Replace(pattern, replacement, options) prend une instance de FindReplaceOptions pour contrôler FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, la direction de la recherche FindReplaceOptions.Direction (une valeur FindReplaceDirection de Forward ou Backward), le formatage appliqué au texte de remplacement (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat), et quels contenus environnants laisser intacts (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes, ainsi que les indicateurs Ignore* associés). Pour une logique par correspondance plus complexe qu’une simple substitution, implémentez la méthode Replacing(args) de IReplacingCallback et assignez l’implémentation à FindReplaceOptions.ReplacingCallback ; chaque correspondance rappelle avec un ReplacingArgs décrivant la correspondance, et la valeur de retour du rappel — une valeur ReplaceAction de Replace, Skip ou Stop — détermine ce qui adviendra de celle-ci.
Combinaison et clonage de documents
Document.AppendDocument(srcDoc, importFormatMode) ajoute le contenu complet d’un Document à la fin d’un autre. Son argument importFormatMode — une valeur ImportFormatMode de UseDestinationStyles, KeepSourceFormatting ou KeepDifferentStyles — détermine comment les conflits de style entre la source et la destination sont résolus, et la surcharge Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) ajoute un contrôle plus fin via ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists et des indicateurs similaires). Pour insérer le contenu d’un autre document à une position précise au lieu de la fin, DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) effectue l’équivalent depuis la position actuelle du curseur du builder, et DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) insère le même contenu sans ajouter de saut de paragraphe ou de section au point d’insertion. Document.ImportNode(srcNode, isImportChildren) copie un nœud — éventuellement avec ses enfants — d’un document différent afin qu’il puisse être ajouté au document en cours, et la méthode Node.Clone(isCloneChildren) disponible sur tout nœud duplique la structure au sein du même document, par exemple en réutilisant une Section comme modèle pour du contenu répété.
Signets et variables de document
La propriété Range.Bookmarks expose une BookmarkCollection d’ancres nommées à l’intérieur de cette plage. DocumentBuilder.StartBookmark(bookmarkName) et EndBookmark(bookmarkName) marquent l’étendue d’un signet lors de la construction ; l’indexeur BookmarkCollection, bookmarks[name], en récupère un plus tard pour la navigation DocumentBuilder.MoveToBookmark(bookmarkName) ou pour lire Bookmark.Text. Séparément, Document.Variables — une VariableCollection — stocke des paires chaîne nom/valeur arbitraires directement sur le document lui-même, ce qui est utile pour transporter de petites portions d’état à travers une chaîne de génération de documents sans ajouter de contenu visible.
Démarrage rapide
Aspose.Words FOSS pour .NET est disponible via NuGet :
dotnet add package Aspose.Words.FOSSPour construire à partir du code source à la place :
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Avec une référence de projet à Aspose.Words.csproj en place, le chemin le plus court vers un document suit le même schéma utilisé tout au long de cet article : créez un Document, enveloppez-le dans un DocumentBuilder, appelez Write() ou Writeln() pour ajouter du texte — le formatage défini sur les propriétés Font et ParagraphFormat du builder se propage à chaque écriture subséquente — et appelez Document.Save(fileName) pour l’enregistrer sous .docx, .docm, .dotx, .dotm, Flat OPC, Markdown ou texte brut. Pour modifier un fichier existant au lieu de repartir de zéro, chargez-le directement avec new Document(fileName), déplacez le builder à un emplacement spécifique avec MoveToBookmark(), MoveToParagraph() ou MoveTo(node), et continuez à écrire à partir de là.
Formats pris en charge
| Format | Extension | Lire | Écrire |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| OPC plat (toutes les variantes) | (divers) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
L’arbre de nœuds décrit ci-dessus est disponible de la même manière, quel que soit le format à partir duquel un document a été chargé ou dans lequel il sera enregistré — le DOM est indépendant du format en interne. Ce qui n’est pas inclus dans cette édition, c’est tout ce qui dépend de la mise en page : pas d’export PDF, XPS ou image, et pas d’impression, de sorte que les valeurs de champs dépendant de la mise en page, telles que les numéros de page, sont évaluées à des espaces réservés plutôt qu’étant calculées. Les convertisseurs de formats supplémentaires (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 et WordML) ne sont pas lus ni écrits, et l’exécution de la fusion de courrier, LINQ Reporting et la comparaison de documents ne sont pas incluses. Les développeurs qui ont besoin de ces capacités peuvent passer à la version commerciale Aspose.Words for .NET sans réécrire le code DOM présenté ici, puisque les deux éditions partagent le même API sous-jacent.
Open Source & Licence
Aspose.Words FOSS pour .NET est publié sous licence MIT, gratuit pour une utilisation commerciale et personnelle sans redevances ni restrictions de redistribution. Le code source, y compris le Document, DocumentBuilder, et l’implémentation de l’arbre de nœuds décrite ci-dessus, est disponible dans le dépôt Aspose.Words FOSS for .NET sur GitHub.
