Εισαγωγή
Αυτός ο οδηγός εξετάζει πώς το Aspose.Words FOSS για .NET αντιπροσωπεύει ένα έγγραφο Word στη μνήμη, καθώς και τα API που χρησιμοποιούνται για τη δημιουργία, την πλοήγηση και την τροποποίηση αυτής της αναπαράστασης: DocumentBuilder για διαδοχική συγγραφή, το δέντρο κόμβων (Node, CompositeNode, NodeCollection) για άμεση δομική πρόσβαση, DocumentVisitor για την επεξεργασία κάθε τύπου κόμβου σε μία διεργασία, εύρεση-και-αντικατάσταση μέσω Range και FindReplaceOptions, και τις μεθόδους για συνδυασμό και κλωνοποίηση εγγράφων. Where η ανάρτηση ανακοίνωσης παρουσιάζει τη βιβλιοθήκη στο σύνολό της, αυτός παραμένει εστιασμένος στο μοντέλο αντικειμένου εγγράφου (DOM) — η μεγαλύτερη περιοχή της επιφάνειας του API — και στο πώς τα κομμάτια του ταιριάζουν μεταξύ τους.
Aspose.Words FOSS για .NET κυκλοφορεί υπό την άδεια MIT χωρίς εγγενείς εξαρτήσεις· στοχεύει στο .NET Standard 2.0, έτσι το DOM που περιγράφεται εδώ είναι διαθέσιμο στο .NET Framework 4.6.2+ και .NET 6, 8 και 10, σε Windows, Linux και macOS. Εγκαταστήστε το μέσω NuGet, ή δημιουργήστε το από πηγαίο κώδικα — δείτε το Quick Start παρακάτω.
Κάθε εργασία που περιγράφεται παρακάτω — η σύνταξη μιας αναφοράς από το μηδέν, η αναδιάρθρωση ενός υπάρχοντος αρχείου .docx, η διερεύνηση του περιεχομένου του για ανάλυση ή η συναρμολόγηση πολλαπλών εγγράφων σε ένα — ξεκινά από το ίδιο μικρό σύνολο βασικών τύπων: Document, DocumentBuilder και η ιεραρχία Node που τα βρίσκει κάτω.
Το Document Object Model
Δημιουργία εγγράφων με DocumentBuilder
DocumentBuilder είναι ένας συγγραφέας βασισμένος σε κέρσορα που βρίσκεται πάνω σε ένα Document και εισάγει περιεχόμενο διαδοχικά. Οι μέθοδοι Write(text) και Writeln(text) προσθέτουν κείμενο στην τρέχουσα θέση· InsertParagraph() και InsertBreak(breakType) προσθέτουν παραγράφους και αλλαγές σελίδας/στήλης/ενότητας. Η μορφοποίηση είναι καταστατική: οι ιδιότητες Font, ParagraphFormat, ListFormat και PageSetup του builder εφαρμόζονται σε όλα όσα γράφονται μετά, και οι PushFont() / PopFont() αποθηκεύουν και επαναφέρουν την τρέχουσα κατάσταση γραμματοσειράς ώστε μια προσωρινή αλλαγή στυλ να μην χρειάζεται να αναιρεθεί χειροκίνητα. Οι μέθοδοι πλοήγησης μετακινούν τον κέρσορα οπουδήποτε σε ένα υπάρχον έγγραφο — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex), και η γενικού σκοπού MoveTo(node) — και τα DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph και DocumentBuilder.CurrentSection αναφέρουν πού βρίσκεται επί του παρόντος ο builder. Για εξαγωγή κειμένου μόνο για ανάγνωση όπου δεν απαιτείται πλήρες DOM, το PlainTextDocument προσφέρει μια ελαφρύτερη διαδρομή: το new PlainTextDocument(fileName) εκθέτει μόνο την ιδιότητα PlainTextDocument.Text και τις ενσωματωμένες και προσαρμοσμένες ιδιότητες του εγγράφου.
Το Δέντρο Κόμβων: Ενότητες, Παράγραφοι, Τμήματα και Πίνακες
Ένα Document είναι ένα δέντρο από αντικείμενα Node που ρίζεται στο ίδιο το έγγραφο: Section → Body → Paragraph → Run για το κυρίως κείμενο, με Table → Row → Cell να διακλαδώνεται όπου εμφανίζεται ένας πίνακας. Η CompositeNode, η βασική κλάση για κάθε κόμβο-container, εκθέτει CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling και Node.PreviousSibling για άμεση περιήγηση, GetChildNodes(nodeType, isDeep) για τη συλλογή κάθε κόμβου ενός δεδομένου NodeType (Paragraph, Run, Table κ.λπ.) σε οποιοδήποτε βάθος, και GetChild(nodeType, index, isDeep) για αναζητήσεις με δείκτη. Οι μέθοδοι AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) και RemoveChild(oldChild) τροποποιούν άμεσα το δέντρο. Η CompositeNode.SelectNodes(xpath) και η SelectSingleNode(xpath) επιλέγουν κόμβους με έκφραση τύπου XPath αντί να περιηγούνται το δέντρο χειροκίνητα, και για πολύ μεγάλα έγγραφα, οι Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) διασχίζουν κάθε κόμβο έναν προς έναν χωρίς αναδρομή.
DocumentVisitor: Επεξεργασία Κάθε Τύπου Κόμβου σε Μία Πορεία
Η υποκλάση του DocumentVisitor είναι ο τρόπος για την επεξεργασία ενός εγγράφου χωρίς σκληρή κωδικοποίηση της δομής του. Ορίζει ζευγαρωμένες μεθόδους Visit-Start / Visit-End για κάθε τύπο σύνθετου κόμβου, συμπεριλαμβανομένων των DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart και DocumentVisitor.VisitBookmarkStart — καθένα με το αντίστοιχο End callback — καθώς και DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd και DocumentVisitor.VisitRun για μεμονωμένα τμήματα κειμένου. Καλείτε Accept(visitor) σε ένα Document, Section ή οποιονδήποτε άλλο κόμβο για να τρέξετε τον επισκέπτη πάνω σε αυτόν τον κόμβο και σε ό,τι βρίσκεται κάτω από αυτόν· τα AcceptStart(visitor) και AcceptEnd(visitor) καλούν μόνο τις callbacks εισόδου και εξόδου για έναν ενιαίο σύνθετο κόμβο. Κάθε μέθοδος Visit επιστρέφει μια τιμή VisitorAction που ελέγχει πώς συνεχίζεται η περιήγηση — Continue για να προχωρήσει στο υποδέντρο, SkipThisNode για να το παραλείψει, ή Stop για να διακόψει εντελώς.
Εύρεση και Αντικατάσταση Κειμένου
Η μέθοδος Range.Replace(pattern, replacement) εκτελεί αναζήτηση-και-αντικατάσταση στο Range που το κατέχει — ένα ολόκληρο Document, ένα Section ή την ιδιότητα Range οποιουδήποτε κόμβου — με το μοτίβο αναζήτησης να δίνεται είτε ως κυριολεκτικό κείμενο είτε ως κανονική έκφραση. Η υπερφόρτωση Range.Replace(pattern, replacement, options) δέχεται ένα αντικείμενο FindReplaceOptions για τον έλεγχο του FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, της κατεύθυνσης αναζήτησης FindReplaceOptions.Direction (τιμή FindReplaceDirection Forward ή Backward), της μορφοποίησης που εφαρμόζεται στο κείμενο αντικατάστασης (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat) και του ποίου περιεχομένου γύρω θα παραμείνει αμετάβλητο (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes και σχετικές σημαίες Ignore*). Για λογική ανά αντιστοίχιση πέρα από απλή αντικατάσταση, υλοποιήστε τη μέθοδο Replacing(args) του IReplacingCallback και εκχωρήστε την υλοποίηση στο FindReplaceOptions.ReplacingCallback; κάθε αντιστοίχιση καλεί πίσω με ένα ReplacingArgs που περιγράφει την αντιστοίχιση, και η τιμή επιστροφής του callback — μια τιμή ReplaceAction του Replace, Skip ή Stop — καθορίζει τι θα συμβεί με αυτήν.
Συνδυασμός και Κλωνοποίηση Εγγράφων
Document.AppendDocument(srcDoc, importFormatMode) προσθέτει το πλήρες περιεχόμενο ενός Document στο τέλος ενός άλλου. Το όρισμα importFormatMode — μια τιμή ImportFormatMode του UseDestinationStyles, KeepSourceFormatting ή KeepDifferentStyles — αποφασίζει πώς θα λυθούν οι συγκρούσεις στυλ μεταξύ της πηγής και του προορισμού, και η υπερφόρτωση Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) προσθέτει πιο λεπτό έλεγχο μέσω ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists και παρόμοιων σημαιών). Για να εισάγετε το περιεχόμενο ενός άλλου εγγράφου σε συγκεκριμένη θέση αντί για το τέλος, DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) κάνει το ισοδύναμο από τη τρέχουσα θέση του δρομέα του builder, και DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) εισάγει το ίδιο περιεχόμενο χωρίς να προσθέτει παράγραφο ή αλλαγή ενότητας στο σημείο εισαγωγής. Document.ImportNode(srcNode, isImportChildren) αντιγράφει έναν κόμβο — προαιρετικά με τα παιδιά του — από διαφορετικό έγγραφο ώστε να μπορεί να προσαρτηθεί στο τρέχον, και η μέθοδος Node.Clone(isCloneChildren) διαθέσιμη σε οποιονδήποτε κόμβο διπλασιάζει τη δομή εντός του ίδιου εγγράφου, όπως η επαναχρησιμοποίηση ενός Section ως πρότυπο για επαναλαμβανόμενο περιεχόμενο.
Σελιδοδείκτες και Μεταβλητές Εγγράφου
Η ιδιότητα Range.Bookmarks εκθέτει ένα BookmarkCollection από ονομασμένα άγκυρα εντός αυτού του εύρους. DocumentBuilder.StartBookmark(bookmarkName) και EndBookmark(bookmarkName) σηματοδοτούν την έκταση ενός σελιδοδείκτη κατά τη δημιουργία· ο δείκτης του BookmarkCollection, bookmarks[name], ανακτά ένα αργότερα για πλοήγηση με DocumentBuilder.MoveToBookmark(bookmarkName) ή για ανάγνωση του Bookmark.Text. Αυτοτελώς, το Document.Variables — ένα VariableCollection — αποθηκεύει αυθαίρετα ζεύγη ονόματος/τιμής ως συμβολοσειρές απευθείας στο ίδιο το έγγραφο, χρήσιμο για τη μεταφορά μικρών κομματιών κατάστασης μέσα από μια αλυσίδα δημιουργίας εγγράφων χωρίς να προσθέτει ορατό περιεχόμενο.
Γρήγορη Εκκίνηση
Aspose.Words FOSS για .NET είναι διαθέσιμο μέσω NuGet:
dotnet add package Aspose.Words.FOSSΓια να κατασκευάσετε από πηγαίο κώδικα αντ’ αυτού:
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
Με μια αναφορά έργου στο Aspose.Words.csproj στη θέση της, η πιο σύντομη διαδρομή προς ένα έγγραφο ακολουθεί το ίδιο μοτίβο που χρησιμοποιείται σε όλη αυτήν την ανάρτηση: δημιουργήστε ένα Document, τυλίξτε το σε ένα DocumentBuilder, καλέστε Write() ή Writeln() για να προσθέσετε κείμενο — η μορφοποίηση που ορίζεται στις ιδιότητες Font και ParagraphFormat του builder μεταβιβάζεται σε κάθε επόμενο γράψιμο — και καλέστε Document.Save(fileName) για να το αποθηκεύσετε ως .docx, .docm, .dotx, .dotm, Flat OPC, Markdown ή απλό κείμενο. Για να επεξεργαστείτε ένα υπάρχον αρχείο αντί να ξεκινήσετε από την αρχή, φορτώστε το απευθείας με new Document(fileName), μετακινήστε το builder σε συγκεκριμένη θέση με MoveToBookmark(), MoveToParagraph() ή MoveTo(node), και συνεχίστε τη συγγραφή από εκεί.
Υποστηριζόμενες Μορφές
| Μορφή | Επέκταση | Ανάγνωση | Εγγραφή |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (όλες οι παραλλαγές) | (διάφορα) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Το δέντρο κόμβων που περιγράφηκε παραπάνω είναι διαθέσιμο με τον ίδιο τρόπο, ανεξάρτητα από το σε ποια από αυτές τις μορφές φορτώθηκε ή θα αποθηκευτεί ένα έγγραφο — το DOM είναι εσωτερικά ανεξάρτητο από μορφή. Αυτό που δεν περιλαμβάνεται σε αυτήν την έκδοση είναι οτιδήποτε εξαρτάται από τη διάταξη της σελίδας: δεν υπάρχει εξαγωγή PDF, XPS ή εικόνας, και δεν υπάρχει εκτύπωση, έτσι οι τιμές πεδίων που εξαρτώνται από τη διάταξη, όπως οι αριθμοί σελίδων, αξιολογούνται ως σύμβολα κράτησης θέσης αντί να υπολογίζονται. Οι πρόσθετοι μετατροπείς μορφών (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, και WordML) δεν διαβάζονται ή γράφονται, και η εκτέλεση συγχώνευσης αλληλογραφίας, η αναφορά LINQ, και η σύγκριση εγγράφων δεν περιλαμβάνονται. Οι προγραμματιστές που χρειάζονται αυτές τις δυνατότητες μπορούν να μεταβούν στη εμπορική Aspose.Words για .NET χωρίς να ξαναγράψετε τον κώδικα DOM που εμφανίζεται εδώ, επειδή και οι δύο εκδόσεις μοιράζονται το ίδιο υποκείμενο API.
Ανοιχτός Κώδικας & Άδειες
Aspose.Words FOSS για .NET εκδίδεται υπό την άδεια MIT, δωρεάν για εμπορική και προσωπική χρήση χωρίς δικαιώματα ή περιορισμούς αναδιανομής. Η πηγή, συμπεριλαμβανομένου του Document, DocumentBuilder, και η υλοποίηση του δέντρου κόμβων που περιγράφηκε παραπάνω, είναι διαθέσιμη στο Aspose.Words FOSS για .NET αποθετήριο στο GitHub.
